Specfold

A local-first desktop API collection studio for OpenAPI, Swagger, Postman, Insomnia, HAR, cURL, and gateway request workflows.

gatewaylabs.net/specfold / Download v1.9.3 / Security review

Specfold helps developers turn API specifications into a practical request workspace:

OpenAPI / Swagger / Postman / Insomnia / HAR / .http / cURL
        -> editable collections, folders, and requests
        -> local environments and scoped collection/folder base URLs
        -> request testing, response inspection, and variable capture
        -> OpenAPI, Postman v2.1, .http, and native Collection JSON export

It is intentionally local-first. There is no account requirement, no cloud workspace, and no hosted sync layer. Your workspace, environments, request history, and secrets stay on the machine running the desktop app.

The published stable release is v1.9.3. It resolves common baseUrl aliases against the scoped collection or folder route, gives incomplete token requests a direct URL-editing path, and makes collection collapse controls easier to reach. See the release notes and desktop runtime decision.

Download v1.9.3

Platform	Package	Download
Windows x64	Installer	Specfold-1.9.3-x64.exe
Windows x64	Portable app	Specfold-1.9.3-x64-portable.exe
macOS Apple Silicon	DMG	Specfold-1.9.3-mac-arm64.dmg
macOS Apple Silicon	ZIP	Specfold-1.9.3-mac-arm64.zip
macOS Intel	DMG	Specfold-1.9.3-mac-x64.dmg
macOS Intel	ZIP	Specfold-1.9.3-mac-x64.zip
Linux x64	AppImage	Specfold-1.9.3-linux-x86_64.AppImage
Linux x64	Debian package	Specfold-1.9.3-linux-amd64.deb
All platforms	SHA-256 checksums	SHA256SUMS.txt

Release page: github.com/Gatewaylabsnet/specfold/releases/tag/v1.9.3. Earlier releases remain available from the release archive.

Verify a downloaded package against the published checksums:

sha256sum -c SHA256SUMS.txt --ignore-missing

On Windows PowerShell, compare Get-FileHash .\Specfold-1.9.3-x64.exe -Algorithm SHA256 with the matching line in SHA256SUMS.txt.

Unsigned Windows builds may trigger SmartScreen. Unsigned and non-notarized macOS builds may require opening from Finder with Open to confirm the Gatekeeper prompt.

See the Code signing policy for signing scope, approval roles, build provenance, privacy, and the current SignPath Foundation application status. Release artifacts remain unsigned until that policy explicitly states that signing is active.

v1.9.3 Highlights

• Requests using {{baseURL}}, {{base_url}}, or {{base-url}} now receive the same scoped collection and folder routing as {{baseUrl}}.
• Token requests with an empty or unresolved endpoint show a direct, editable URL path instead of leaving the missing configuration unclear.
• Selecting the active collection name now also expands or collapses it; the dedicated arrow remains available.
• The shipped Windows portable application is exercised end to end in CI, covering import, routing, file uploads, backup/restore, and guarded data deletion.

v1.9.2 Highlights

• The top-bar Manage action opens connection profiles directly, so switching from sending a request to editing an environment takes one clear step.
• Environment name, variables, and scoped base URL edits stay local while you type and commit on blur or Enter. Large imported collection trees are not copied for each keystroke.
• Delete all data disables the action while it runs, prevents queued stale saves from restoring deleted content, and returns to one fresh Specfold environment.

v1.9.1 Highlights

• Postman and compatible import variables are now opt-in. Importing a collection does not create or activate an environment unless you choose Import source variables as a new environment.
• A Postman baseUrl remains a collection route, so {{baseUrl}} still resolves without duplicating it into the active environment.
• Import notices explain when source variables were intentionally left out, helping you add token or client variables only when the collection needs them.

v1.9.0 Highlights

• Base URL defaults and collection/folder overrides are edited together in Environments, without an environment edit overwriting a scoped route.
• Request and response panels resize with a pointer or keyboard, and response text has persistent A−/A+ sizing.
• Test a configured endpoint before sending a request, including protected endpoints that return an expected authentication status.
• Pin high-value requests, focus request search with Ctrl/Cmd+K, and see imported request/folder counts immediately after import.
• Inspect JSON in raw or formatted form, find content in the response, and copy response or error details quickly.
• Settings now disclose the local data location and automatic safety-backup state, with an explicit action to open the data folder.
• Update checks remain manual and never download or install packages automatically.

What It Does

• Imports OpenAPI 3.x, Swagger 2.0, Postman Collection v2.0/v2.1 JSON and v3 YAML folders, Insomnia JSON v4/v5, HAR 1.2, .http/.rest, Specfold Collection JSON, and curl commands.
• Preserves portable collection folders, supported auth modes, request bodies, and response examples. Source variables can be imported into a separate environment only with explicit opt-in.
• Lets you select exactly which operations to import before creating requests.
• Previews a safe re-import before merging new source changes; matched request IDs, custom auth, bodies, and saved examples are retained, and existing requests are never deleted.
• Groups imported endpoints by tag, first path segment, or a single folder.
• Organizes APIs into collections, folders, and requests with search, rename, duplicate, delete, and drag-and-drop movement.
• Pins frequently used requests at the top of their folder and focuses request search with Ctrl/Cmd+K.
• Collapses collections and nested folders independently while keeping search matches visible without losing the previous expanded state. An active collection name is also a larger expand/collapse target.
• Shows only the selected routing scope for base URL editing, alongside the effective URL and its environment, collection, or folder source.
• Edits request method, URL, query params, path params, headers, body, and auth.
• Builds multipart/form-data bodies with text and file rows, repeated field names, native file selection, and an automatically generated boundary.
• Supports bearer token, basic auth, API key auth, and no-auth request modes.
• Includes portable OAuth Client Credentials and Password Grant token recipes.
• Sends HTTP requests from the desktop app and shows status, timing, size, headers, body, raw response, and per-request history. Drag the horizontal divider to give either panel more room, and use A−/A+ to persist a comfortable response text size.
• Copies any request as a curl command.
• Formats JSON responses, searches response content, and copies response or error details from the inspector.
• Copies generated export content directly from the preview to the clipboard.
• Saves JSON response fields directly into environment variables.
• Exports a whole collection or selected folders as OpenAPI YAML/JSON, Postman Collection v2.1, .http, or native Collection JSON.
• Exports a complete local backup containing collections, environments, settings, and secrets after an explicit security warning.
• Permanently deletes all local content, settings, and rotating backups through a two-step confirmation.
• Shows the installed version and manually checks for newer GitHub Releases from the top-bar About dialog.
• Runs an export structure check before saving generated OpenAPI.

Supported Import Formats

Format	Accepted input	Notes
OpenAPI 3.0/3.1	JSON, YAML	Local references, multipart schemas, and source-operation fidelity
Swagger 2.0	JSON, YAML	Request model conversion, including multipart formData
Postman 2.0/2.1	Collection JSON	Folders, collection base URL, optional source variables, auth, bodies, multipart placeholders, examples
Postman 3	Multi-file YAML folder	Optional source variables; scripts and symlinks are skipped
Insomnia 4/5	Export JSON	Workspaces, folders, optional environments, multipart placeholders, responses
HAR 1.2	JSON	Captured requests, multipart placeholders, and response examples
HTTP files	.http, .rest	Declarative requests only; scripts are not executed
Specfold	Collection JSON	Native portable collection
cURL	Command text	Common method/header/body/auth flags and -F/--form fields

Malformed or unsupported records are reported without executing imported scripts. Folder imports are bounded by depth, file count, and total bytes.

Base URLs And Environments

Specfold separates environment defaults from collection- and folder-level routing:

• Every workspace starts with an active Specfold environment; environments can be renamed, and the final environment cannot be deleted.
• Environment baseUrl is the default route for new collections and requests without a more specific route.
• New collections copy the active environment baseUrl as their starting collection base URL.
• Collection baseUrl overrides the environment baseUrl when requests resolve {{baseUrl}}. Common aliases {{baseURL}}, {{base_url}}, and {{base-url}} follow the same rule.
• A folder baseUrl overrides both values for every request below that folder; nested folders inherit the nearest configured parent and can override it again.
• Absolute request URLs always stay unchanged. Relative request URLs are joined to the effective base URL, so both /orders and {{baseUrl}}/orders are supported.
• Collection and folder baseUrl values are managed in the Environment routing view. Leaving an override empty restores inheritance.
• A folder can also reference an environment secret such as ordersAccessToken. Nested folders inherit the nearest configured token variable independently from base URL inheritance.
• The request workspace shows the resolved effective URL and source beside the request without duplicating the routing fields.
• Changing an environment baseUrl never changes collection or folder base URL overrides.
• Imported OpenAPI/Swagger servers are mapped into collection base URL data.
• A Postman collection baseUrl is mapped to the collection route. Other imported source variables are optional and never replace the selected environment.

Effective precedence is: absolute request URL, nearest folder baseUrl, collection baseUrl, then environment baseUrl. This keeps two proxy folders isolated inside one collection.

Apinizer JWT Workflow

Specfold includes an Apinizer-focused JWT request template:

1. Import an OpenAPI/Swagger document exported from Apinizer.
2. Create an Apinizer JWT request from the New menu.
3. Specfold creates an Apinizer Auth folder and derives its base URL from the API origin when possible. For example, https://api.tarimorman.gov.tr/dats/cks becomes https://api.tarimorman.gov.tr, producing https://api.tarimorman.gov.tr/auth/jwt.
4. Review or override the folder base URL, then set environment values such as username, password, and clientId.
5. Send the token request.
6. Use Save as folder token on the response to store access_token as a folder-specific encrypted environment secret.
7. On bearer requests in that folder or its children, choose Use folder token. Specfold inserts the inherited {{variableName}} reference without copying the token into the request.
8. Export the selected folder or collection as OpenAPI YAML/JSON.

Form Data And File Uploads

Choose Body -> Form data for endpoints that accept multipart/form-data:

1. Add a text field or file field.
2. Enter the field name expected by the API. Duplicate names are allowed for multi-file endpoints.
3. For a file field, choose the file through the native picker. The optional media type defaults from the file extension.
4. Send the request. Specfold generates the multipart boundary and Content-Type header automatically.

Imported OpenAPI, Swagger, Postman, Insomnia, HAR, and cURL file fields are safe placeholders: their local source paths are not trusted or read. Choose each file again before sending. Files are referenced for the current app session only and are not embedded in exports or backups.

About And Update Checks

Open About in the top bar to see the installed Specfold version, platform, architecture, license, current release link, and download page. The dialog closes from its close button, the backdrop, or the Escape key.

The Check for updates button reads the latest GitHub Release metadata and compares it with the installed version. If a newer version is available, Specfold shows release notes and download links. It does not download packages, install updates, or run installers automatically.

Data And Security

• Workspaces are saved locally using atomic writes.
• Rotating workspace backups are kept, and Settings shows their count and latest safety-backup time.
• Settings can open the local data folder explicitly; the application does not expose it automatically.
• Corrupt workspace files are quarantined instead of overwritten.
• Environment variables marked secret are encrypted at rest with Electron safeStorage.
• Complete backup exports intentionally contain readable secret values, require explicit confirmation, and use 0600 permissions where supported.
• Restore accepts only specfold.backup.v1, caps reads at 100 MB, validates workspace/settings, creates a safety copy, re-encrypts secrets, and rolls back both files on failure.
• If encryption is unavailable, secret values are never persisted as plaintext and the application shows a persistent warning.
• Export warnings flag literal values that look like secrets.
• Parameter and header values are not emitted as OpenAPI examples unless explicitly enabled.
• Unused component schemas are pruned from folder-scoped exports by default.
• HTTP requests use configurable timeouts and capped response bodies.
• Upload files are granted only after an explicit native file-picker selection. Specfold keeps an opaque, session-only reference in memory; local paths and file bytes are never written to the workspace, backup, Collection JSON, or OpenAPI export.
• Multipart requests allow at most 200 parts, including at most 50 files, and 100 MB of file and text content per send. Files must be selected again after restarting the app, restoring a backup, or importing a collection.
• Insecure TLS is opt-in.
• System proxy rules are used, with HTTP_PROXY / HTTPS_PROXY fallback.
• The desktop renderer runs with contextIsolation: true, nodeIntegration: false, sandbox: true, and a packaged Content Security Policy.

See docs/REDTEAM_REPORT.md for the v1.1 security review, threat model, closed findings, and remaining release risks.

Backup, Restore, And Delete

Open Settings -> Data management:

1. Export backup asks whether to include readable secrets, then writes the complete workspace and settings.
2. Restore backup confirms replacement, validates the selected file, and reports the pre-restore safety-copy path on success.
3. Delete all data requires both a warning confirmation and exact DELETE ALL text. It blocks stale queued saves, removes workspace, settings, rotating/safety backups, and quarantined workspace files, then creates a fresh Specfold environment.

Backup files are sensitive because they intentionally include secrets. Store them in an encrypted location and delete copies you no longer need.

Installation Notes

Windows

Download the installer or portable .exe. If SmartScreen appears, verify the file came from the GitHub release and choose More info -> Run anyway.

macOS

Download the .dmg or .zip for your architecture:

• Apple Silicon: arm64
• Intel: x64

Because v1.9.3 is not notarized, macOS may require opening the app from Finder with Open.

Linux

Download the .AppImage or .deb.

chmod +x Specfold-1.9.3-linux-x86_64.AppImage
./Specfold-1.9.3-linux-x86_64.AppImage

For Debian-based distributions:

sudo dpkg -i Specfold-1.9.3-linux-amd64.deb
sudo apt-get install -f

Project Layout

apps/desktop/src/main                 Electron bootstrap and testable services
apps/desktop/src/shared/contracts.ts  Shared main/preload/renderer IPC contracts
apps/desktop/src/renderer/app         Controller hooks and screen modules
apps/desktop/src/renderer/components  Tree and key/value editor components
packages/core/src/importers/portable  Postman, Insomnia, HAR, and HTTP importers
packages/core/src/exporters/openapi   OpenAPI assembly, operations, security, warnings
docs/                                 Product, architecture, UI, and security specs

Development

Requires Node.js 20+ and npm 10+.

npm install
npm run dev
npm run typecheck
npm test

Packaged Windows E2E

The end-to-end suite opens the real unpacked Electron executable with an isolated temporary profile and a local HTTP test server. It covers native import/file-picker IPC, environment routing, request/response handling, multipart upload, export, full backup/restore, and destructive-data confirmation.

npm run test:e2e:packaged

To rerun the E2E suite against an already-built portable package, use npm run test:e2e. On failure, Playwright keeps traces, screenshots, and videos in apps/desktop/e2e/artifacts.

Build Locally

npm run package:win:portable     # Windows portable .exe
npm run package:win:installer    # Windows NSIS installer
npm run package:win              # Windows portable + installer
npm run package:mac              # macOS dmg + zip, x64 + arm64; run on macOS
npm run package:linux            # Linux AppImage + deb, x64; run on Linux

Artifacts are written to apps/desktop/dist.

Release

Run the release workflow manually first. workflow_dispatch builds and verifies every package plus SHA256SUMS.txt without creating a tag or release. Tag pushes run the same package gate and create a draft GitHub Release.

git tag -a v1.9.3 -m "Specfold v1.9.3"
git push origin main
git push origin v1.9.3

Public release assets are only the two Windows packages, four macOS packages, Linux AppImage/DEB, and SHA256SUMS.txt. Builder debug YAML, updater YAML, and blockmaps are excluded. The generated release stays draft until manual smoke tests pass.

Known Limitations

• Release builds are not code-signed yet.
• macOS builds are not notarized yet.
• Complete backups are plaintext by design and may contain secrets.
• Very large imports/exports can still use the renderer thread, within configured size limits.
• Automatic update download and installation are not implemented in v1.9.3; use Help -> Check for Updates to check manually and download from the release page.
• SOCKS proxies are not supported; configure an HTTP(S) proxy for Specfold.
• Multipart uploads are capped at 200 parts, 50 files, and 100 MB of file and text content per request; selected files must be chosen again after an app restart.

License

Specfold is licensed under the Apache License 2.0.