Skip to content

ADR 0034 — Shared Postman parser and _postman sidecar

Accepted · 2026-10-26 · amended 2026-10-27, 2026-10-28

Postman v2.x import lived in the renderer (src/features/collections/lib/importers/postman.ts) on top of the postman-collection SDK. That had three problems:

  • No CLI path. The CLI and other runtime-neutral code cannot import renderer src/, so a second importer would have been needed for restura CLI import (#1202).
  • Silent loss. Unsupported auth (hawk, edgegrid, jwt, akamai, and OAuth1 / NTLM, which Restura does support) became none with no warning. Saved responses, protocolProfileBehavior, item variables, extra same-kind events, file-body paths and OAuth2 implicit / PKCE details were dropped without a trace.
  • No room for v3. Postman Collection v3 (epic #1197) is a multi-file YAML folder whose objects are all additionalProperties: false. The SDK cannot read it, and v3 must reach the same internal model as v2.1.
  1. One SDK-free parser in shared/collections/postman/. It runs anywhere (no DOM, no src/ imports) and is used by the renderer importer (now a thin adapter) and by the CLI (#1202). Version front ends (parse-v2.ts for v2.0 / v2.1, parse-v3.ts for v3, #1200) feed one normalised path. They share the auth mapping (auth.ts, which also owns the single walk over v2.1 array / v2.0 map parameter blocks), the report (report.ts), the sidecar (sidecar.ts) and its redaction (redaction.ts). importPostmanCollection(data, { transformScript }) → { collection, report }. transformScript defaults to the pm.* → rs.* migration, which now lives in shared/scripts/script-migrations.ts (the old renderer path re-exports it). URL path variables (:id segments with url.variable values) are substituted as the old SDK did, because Restura has no :param runtime.
  2. No silent loss. Every construct that is dropped or approximated produces a structured report entry (the shapes are a subset of the renderer’s ImportWarning, so the UI and CLI print them unchanged). Its raw Postman JSON is also kept in a _postman sidecar on the collection, folder or request item it came from. That includes an unsendable method (imported as GET), form-data file rows (imported empty, because a file row’s value holds file bytes, not a path) and partly applied URL path variables. Export has its own report (export-report.ts, #1201) that lists what v3 cannot hold. OAuth1 and NTLM now map 1:1. Unsupported auth becomes none with a warning and the raw active block in the sidecar (hasUnsupportedPostmanAuth recognises such a node). A request that inherits from a folder or collection with unsupported auth gets an explicit none plus a report entry, so it never picks up a credential from further up; the CLI refuses to send it (“not sent”), and v3 export keeps that container auth inherited instead of inventing a credential. OAuth2 implicit / PKCE and OAuth1 RSA, body/URL placement and unsupported signature methods map approximately, with a warning and only the unmapped keys in the sidecar. Mapped typed credentials import inline exactly as before; they become handles only through the existing “store secrets as handles” opt-in. v3 vault-secret variables import value-less with a warning.
  3. The sidecar lives in Restura only, and behaves like OpenCollection’s _oc. The import gate keeps the original object, so _postman survives validation. useCollectionStore strips _oc and _postman together along the mutation path, so a bag never describes a request the user has since edited. The root _postman is dropped when collection auth, variables or scripts actually change. Every path that strips or duplicates bags uses one list, PASSTHROUGH_BAG_KEYS (shared/collections/passthrough-bags.ts). The sidecar is stored raw (in memory and in the persisted store), not redacted. It is redacted on export and on handle conversion: shared/secrets/collection-redaction.ts applies shared/collections/postman/redaction.ts to every bag wherever _oc bags are handled, because bags can carry credentials. That covers hawk keys, edgegrid tokens, jwt secrets and OAuth secrets, plus saved-response headers in every shape, cookies, bodies, and original-request URL userinfo and credential query parameters. The export-warning count matches exactly what redaction blanks. The sidecar never holds a second copy of mapped credentials (ADR-0007). With handle storage on, convertCollectionSecretsToHandles turns bag-only auth credentials into keychain handles and blanks every other secret-bearing value; if the keychain rejects, it fails closed. Import rejects folder nesting deeper than 64 levels. Report entries carry only names and fixed notes, and sidecar contents are never logged.
    • The sidecar is never written into v3 files (the v3 schema forbids extra properties). Export only reads it (already redacted) to restore what the importer could not model, such as unsupported-kind placeholders and bag-only auth; it never writes back to it.
    • Known limitation: in the app, Restura’s none auth means “inherit”, so a request whose Postman auth was unsupported (or an explicit Postman “No Auth”) can pick up a parent’s credentials at send time. The import report flags these requests. Superseded by Amendment (i): such requests are now refused at send on every platform.
    • It is store-scoped. It is not part of the git-native file format, so a desktop file-backed collection loses it on save and reload (the IPC collection schema drops unknown root keys). That is intentional. Keeping it would need a redacted x-restura-postman extension later.
  4. Formats (#1200 / #1201 / #1202). v2.1 (single JSON file) stays the default export; Postman v3 (folder / zip) is a second menu item. v3 on disk is a YAML folder. Import accepts a folder, a zip or a single JSON/YAML file, with caps (50 MB archive, per-file, total, count and depth limits; traversal refused). Export writes <picked>/<name>/ on Electron and <name>.postman-v3.zip on the web. The desktop write asks before replacing a non-empty folder and then removes only Postman layout files, so unrelated files in that folder survive. (The default-export part is superseded by Amendment (a).)
  5. MCP stdio items from a v3 import arrive disabled. An imported file must never be able to launch a local process, so a stdio item becomes a disabled placeholder folder with a report warning, and neither the app nor the CLI can run it. Its sidecar keeps only the launch shape (the executable, option names and env variable names); every argument and env value is blanked, fail-closed, because a command line can carry credentials in shapes no heuristic reliably spots. To use the server, recreate it as an MCP request and re-enter its arguments; the per-launch consent prompt (ADR 0030) still applies.
  6. The importer no longer uses the postman-collection SDK, but the runtime dependency stays. @types/postman-collection is removed. The postman-collection package itself is kept on purpose: the script sandbox bundles it (scripts/build-sandbox-libs.mjs) so user scripts can call require('postman-collection'), which is documented Postman compatibility (docs/postman-compat.md). Removing it would break that. The dependency now exists only for the sandbox, not for import.
  7. The v3 schema is vendored and its types are generated (#1198). vendor/postman/v3.0.0/schema.json is the source. npm run gen:postman-v3-types regenerates shared/collections/postman/v3-types.ts, and npm run verify:postman-v3-types (part of validate:static) fails on drift, like the OpenCollection types gate.
  • Keep the SDK for v2.1 and write a v3 parser beside it. Rejected. It means two internal paths, the SDK still cannot run outside the renderer bundle cheaply, and the silent drops would remain.
  • Drop unmodelled constructs with only a warning. Rejected. Re-export and future features (saved responses, examples) would have nothing to work from.
  • Embed the sidecar in exported files. Rejected. v3 is additionalProperties: false, and an embedded bag would re-emit stale or secret data.
  • One place to fix Postman parsing for the renderer and the CLI. v3 adds a front end, not a second importer.
  • Users see what was lost or approximated at import time.
  • Each new sidecar field must be added to redactPostmanBag / countPostmanBagInlineSecrets (shared/collections/postman/redaction.ts), and each newly mapped auth key to POSTMAN_MAPPED_AUTH_PARAMS (auth.ts). Otherwise secrets are duplicated, double-counted or missed.
  • The root _oc is still not stripped by updateCollection: internalToOC re-checks root auth and scripts against the live model before it uses the cached root.
  • Code: shared/collections/postman/, shared/collections/passthrough-bags.ts, shared/scripts/script-migrations.ts, src/features/collections/lib/importers/postman.ts, src/store/useCollectionStore.ts (stripPassthroughBags), shared/secrets/collection-redaction.ts, src/lib/shared/secretRef-migrations.ts, tests/security/postman-sidecar-secret-leak.test.ts
  • Issues: #1197 (epic), #1198, #1199, #1200, #1201, #1202, #1203
  • Related: ADR 0007 (SecretRef pattern)
  • (a) v3 is now the default export, superseding “v2.1 stays the default” in decision 4. Why: v3 is Postman’s current format; v2.1 stays in the menu for Newman.
  • (b) MCP stdio imports become an empty placeholder folder with no request object, replacing the disabled request in decision 5. Why: with no request, nothing (runner, workflows, CLI, Electron) can ever launch it. The launch shape is kept in the sidecar with fail-closed argv: exec, option names and env names are kept, every value is blanked.
  • (c) WebSocket / Socket.IO items import as placeholders until native items exist (#1209). Why: Restura has no collection item kind for them yet.
  • (d) postman-collection stays a dependency only for the script sandbox, as in decision 6. Why: the sandbox’s require('postman-collection') needs it; the importer and exporters never use it.
  • (e) The v2.1 schema is vendored (vendor/postman/v2.1.0) and STRICT generated PostmanV21* types are used for export. Import stays lenient and runtime-guarded and reports off-schema values. Why: export must emit schema-valid files, while real-world Postman files routinely stray from the schema.
  • (f) The v2.1 exporter moved to shared/collections/postman/export-v2.ts and shares the export report with v3. Why: one runtime-neutral exporter for the renderer and CLI, with one report shape.
  • (g) The v2.1 export format id is renamed 'postman' to 'postman-v21'. Why: with two Postman export formats, a bare 'postman' is ambiguous.
  • (h) v2.1 type: "secret" variables import value-less with a warning. Why: Postman emits them although the v2.1 schema does not define them, and their values must not be copied into a Restura collection.
  • (i) Imported Postman noauth and unsupported auth are guarded at send, as an interim measure until native modelling (#1232). An explicit noauth is marked _postman.noauth and cuts inheritance; a request that would otherwise receive an ancestor credential it should not (explicit noauth below a configured ancestor, or anything below an unsupported-auth folder) is refused (“Not sent”) on web, desktop and CLI, across single send, the runner, workflows and AI Lab tools. Why: Restura’s none means inherit, so without the guard an import silently sends a credential Postman would not. explicit-noauth joins the import report and export writes an explicit noauth. Residual limitation: formats with no _postman sidecar do not carry the guard markers. OpenCollection export / re-import and saving a Postman import into a git-native folder write Restura none as omitted (shared/opencollection/auth-from-internal.ts), which means inherit, so after such a round trip the request inherits the ancestor credential again. The guard holds while the collection stays in Restura’s store (and Postman export); until #1232 adds an explicit no-auth to the model, set the auth explicitly on those requests before saving to those formats.
  • (j) Export redacts credential-named form rows. With secrets excluded, urlencoded / form-data text rows such as client_secret and password, and nested OAuth2 values (client_assertion, code_verifier, assertion), are counted by the prompt and blanked in every exporter (Postman, Insomnia, OpenCollection, Bruno). Why: these rows carry the same secrets as auth fields but sat outside the auth model. Git-native desktop files are unchanged (#1234).
  • (k) Environment-file secret policy (#1231). Postman (type: "secret"), Hoppscotch (secret: true) and Bruno (vars:secret, in a Bruno directory or .zip import) environment-file variables keep their value on desktop, like a hand-typed secret env var (the env store is encrypted IndexedDB under a safeStorage-protected key). On web and self-host the value is dropped, with one secret-variable warning per key that never carries the value. All three importers share applyEnvironmentSecretPolicy. The CLI does not read Postman environment files.
  • (l) Inherited auth reuses the ancestor’s handles on desktop (#1226). When converting imported secrets, convertCollectionSecretsToHandles lets a request whose whole auth equals its nearest ancestor’s (sameAuth) reuse that ancestor’s handles, so Postman v3 / v2.1 export emits inherit. The ancestor chain is cut by explicit noauth or unsupported auth, exactly as in the exporters’ authForChildren, and reuse never crosses siblings. Consequence: handle ids can be shared. This is safe because SecretInput always mints a new handle on edit and deleting a request or collection never reaps handles; a manual delete in Settings → Secrets affects every location sharing that handle.
  • (m) WebSocket / Socket.IO become native collection items (#1209). Postman v3 websocket-request and socket.io-request items now import as native websocket / socketio items (shared/types/stream-preset.ts) instead of placeholder folders, and v3 export writes them back; Restura-only options are listed as websocket-extras / socketio-extras in the export report. Legacy placeholder folders that hold a WebSocket / Socket.IO _postman.item are upgraded on load (collection store persist version 3 → 4) and on import. Secret-bearing fields (URL userinfo, credential query params, headers, Socket.IO handshakeAuth) are redacted on export but are not converted to keychain handles, matching HTTP headers. The CLI skips them with a [restura] skipping WebSocket preset … notice, like Kafka / MQTT.
  • (n) URL path variables are kept, not substituted on import. Decision 1’s “substituted as the old SDK did, because Restura has no :param runtime” no longer holds: HTTP requests now carry pathVariables rows, and shared/protocol/path-variables.ts substitutes whole :name path segments at send time in every harness (renderer requestExecutor, collection runner, CLI, code generation). Postman v2.0 / v2.1 / v3 import keeps :id in the URL and fills the rows from url.variable; v2.1 / v3 export writes them back (a secret row is written empty and reported), and OpenCollection carries them as type: 'path' params. Only url.variable entries without a name still go to the sidecar with a report entry.