blankdrive

v0.1.2

Published

18 hours ago

Military-grade secure storage with steganography & Google Drive sync

0High
0Medium
0Low

slasshyoverhere

security encryption steganography password-manager vault aes-256 google-drive

BlankDrive

Client-side, zero-knowledge vault for passwords, notes, TOTP secrets, and encrypted files synced to Google Drive.

Current release: 0.1.2 Release notes: see CHANGELOG.md

What's New In 0.1.2

Fixed desktop installer runtime startup by bundling backend runtime files inside Tauri resources.
Added missing auth guard on /api/cli/run in Web UI (ensureUnlocked()), closing local unauthenticated CLI execution risk.
Optimized vault entry iteration path for large vaults with lower allocation overhead.
Kept desktop install/update flows via CLI: BLANK desktop --install, BLANK update --check, BLANK update --install.

CLI Use Case Demo

BlankDrive CLI use case demo

CLI command names after install:

blankdrive (default)
BLANK (backward-compatible alias)

Client-Only Architecture

BlankDrive is fully client-side:

No backend auth server
No remote token broker
OAuth runs locally with Google directly (loopback + PKCE)
OAuth credentials and tokens are encrypted and stored on your machine

Tech Stack

TypeScript + Node.js CLI
AES-256-GCM for encryption
Argon2id for key derivation
Google Drive API (drive.file + drive.appdata)
Local OAuth loopback callback (127.0.0.1) with PKCE

Requirements

Node.js 18+ (22 recommended)
npm
Google account
Google Cloud project with Drive API enabled

Install

npm install -g blankdrive

Desktop installer (Windows) is now available directly from CLI:

BLANK desktop --install

Or from source:

git clone https://github.com/SlasshyOverhere/BlankDrive.git
cd BlankDrive
npm install
npm run build
npm link

Quick Start

# 1) Initialize vault
blankdrive init

# 2) Configure Google OAuth + connect Drive
blankdrive auth

# 3) Add password
blankdrive add

# 4) Upload encrypted file
blankdrive upload

# 5) List entries
blankdrive list

Primary Use Case

BlankDrive is designed for people who want cloud-backed file/password storage without sending plaintext to any project backend.

Typical real-world flow:

You create a local vault protected by your master password.
You add passwords, notes, and files locally.
BlankDrive encrypts data on-device, then uploads encrypted blobs to your own Google Drive.
On a new machine, you restore using the same Google account and your master password.

Practical examples:

Secure personal document vault (IDs, contracts, statements)
Encrypted off-device backup of sensitive notes and credentials
Cross-device password/note/file access via your own Drive account

Upload/Download Flow (What Actually Happens)

blankdrive upload pipeline:

Verifies vault is unlocked and Google OAuth is connected.
Encrypts file locally with vault entry key (AES-256-GCM + AAD).
Chunks large files at 20 MB per chunk.
Uploads encrypted chunks to either:
- BlankDrive/<your-folder>/ (public mode), or
- appDataFolder (hidden mode)
Stores encrypted metadata in local vault index.

blankdrive download pipeline:

Lists encrypted cloud chunks from selected storage mode.
Downloads chunks (parallel with adaptive concurrency based on free RAM).
Decrypts locally and writes restored file to your target path.

Google OAuth Setup (Step-by-Step)

BlankDrive needs your own Google OAuth Desktop credentials.

1. Create or select a Google Cloud project

Open: https://console.cloud.google.com/

2. Enable Google Drive API

Direct link: https://console.cloud.google.com/apis/library/drive.googleapis.com

3. Configure OAuth consent screen

Google guide: https://developers.google.com/workspace/guides/configure-oauth-consent
Console shortcut: https://console.cloud.google.com/apis/credentials/consent

Recommended:

App type: External (or Internal for Workspace org use)
Add your email and app name
Add test users (if app is not published)

4. Create OAuth Client ID (Desktop app)

Google guide: https://developers.google.com/workspace/guides/create-credentials
Console shortcut: https://console.cloud.google.com/apis/credentials
Select: Create Credentials -> OAuth client ID -> Desktop app

Important:

Use Desktop app, not Web application
BlankDrive uses loopback redirect (http://127.0.0.1:<dynamic-port>)

5. Run auth in BlankDrive

BLANK auth

You will be prompted for:

Google OAuth Client ID
Google OAuth Client Secret

Then BlankDrive opens browser for consent and finishes locally.

6. Update or rotate credentials later

BLANK auth --setup

OAuth Flow (How It Works)

BlankDrive starts a local callback server on 127.0.0.1 (random port).
It builds a PKCE challenge and opens Google consent URL.
Google redirects back to local loopback URL.
BlankDrive exchanges code for tokens.
Tokens and OAuth credentials are encrypted and stored locally under ~/.slasshy/.

Reference:

OAuth native apps: https://developers.google.com/identity/protocols/oauth2/native-app

Cloud Storage Modes

You can use either:

public (default): visible in Drive UI under BlankDrive/<folder>/
hidden: stored in Drive appDataFolder (not visible in Drive UI)

Manage anytime:

BLANK settings
BLANK settings --storage public
BLANK settings --storage hidden
BLANK settings --folder my-device
BLANK settings --storage public --folder my-device

Notes:

In public mode, upload prompts for folder each upload (with saved folder as default).
Switching modes does not automatically migrate existing cloud files.

Commands

All commands can be run as either blankdrive ... or BLANK ....

CLI Commands

BLANK init
BLANK init --restore
BLANK add
BLANK get [search] [--copy] [--show-password]
BLANK list [--filter <term>] [--type passwords|files|notes] [--category <name>]
BLANK edit [search]
BLANK favorite [search]
BLANK favorites
BLANK note [add|view|edit|list]
BLANK audit [--all]
BLANK upload [file]
BLANK download [search]
BLANK delete [search] [--force]
BLANK settings [--storage hidden|public] [--folder <name>]
BLANK auth [--setup|--logout]
BLANK generate [options]
BLANK status
BLANK web [--port <number>] [--open]
BLANK desktop [--release <tag>] [--install]
BLANK update [--check|--install|--scheduled]
BLANK lock
BLANK destruct
BLANK version

Interactive Shell (Extended Commands)

Run with no args:

BLANK

Shell includes additional commands like:

sync
totp / 2fa
breach
duress
autolock
theme
history
auditlog

Desktop and update are also available in shell mode:

desktop --install
update --check

Web UI (Local)

BlankDrive now includes a local web console for vault management (including password/note CRUD and file upload/download):

BLANK web --open

Useful options:

--port <number> (default: 4310)
--open (open the browser automatically)

The web UI runs locally and does not use any remote backend. It only accepts requests via localhost (for example http://localhost:4310).

Desktop App (Tauri)

BlankDrive Desktop is now officially launched for users who want a smoother and more stable local app experience while keeping the same backend logic as CLI/Web.

Same Node runtime/backend as CLI (BLANK web sidecar under the hood)
No separate desktop backend
Same vault, same data, same commands
Faster boot and lighter footprint than Electron-based approach

Install/update directly from CLI:

BLANK desktop --install
BLANK update --check
BLANK update --install

Restore Flow

BLANK init --restore

Restore requires:

Same Google account
Correct vault master password
Correct storage mode/folder location of your backup

Security Specifications

Core crypto and key management:

Encryption algorithm: AES-256-GCM
IV length: 12 bytes
Auth tag length: 16 bytes
KDF: Argon2id
Default Argon2id params: timeCost 3, memoryCost 65536 (64 MB), parallelism 4, hashLength 32
Sub-key derivation: HKDF-SHA256 contexts (index, entry, metadata)
AAD binding: entry ID or chunk-specific ID (<entryId>_chunk_<index>)

Storage and cloud behavior:

Local vault path: ~/.slasshy/
Encrypted token file: ~/.slasshy/drive_token.enc
Encrypted OAuth credentials: ~/.slasshy/google_oauth_credentials.enc
Cloud scopes: drive.file and drive.appdata
Public mode path: Google Drive > BlankDrive/<folder>/
Hidden mode path: Google appDataFolder (not visible in Drive UI)

Performance-related implementation details:

File chunk size: 20 MB
Parallel upload/download worker limit: 5
Adaptive download parallelism:
- 5 workers when free RAM > 2 GB
- 2 workers when free RAM > 512 MB
- 1 worker otherwise

Trust Boundary and Limits

What BlankDrive does:

Runs client-side only in this repo (no project-hosted backend required)
Sends OAuth/auth API requests directly to Google
Encrypts payloads before cloud upload

What BlankDrive does not guarantee:

If your machine is compromised while vault is unlocked, local secrets can be exposed
Losing your master password means encrypted vault data cannot be recovered
Hidden mode (appDataFolder) improves visibility/privacy in Drive UI, but is not a substitute for endpoint security

Troubleshooting

`redirect_uri_mismatch`

Ensure OAuth client type is Desktop app
Then run:

BLANK auth --setup

Upload says success but file is not visible in Drive

You are likely in hidden mode (appDataFolder)
Switch to public mode:

BLANK settings --storage public

Need to re-authenticate

BLANK auth --logout
BLANK auth

Access blocked / unverified app

Add your Google account as a test user in OAuth consent screen settings.

Local Data Paths

Vault and config: ~/.slasshy/
Encrypted token file: ~/.slasshy/drive_token.enc
Encrypted OAuth creds: ~/.slasshy/google_oauth_credentials.enc
Cloud mode config: ~/.slasshy/cloud_storage_config.json

License

MIT