Skip to main content

​
What it is

Credential isolation is the guarantee that a connector, the code that actually calls an external service like HubSpot, GitHub, or Paytm, never holds a long-lived, reusable credential. Instead it receives a single-use, time-bounded session credential, minted fresh for one specific execution, resolved to the real secret only at the last possible moment, and destroyed immediately after use, whether that use succeeded or failed.

​
Why it was built

A connector is the part of this system closest to the outside world, and therefore the part most exposed to a bug, a dependency vulnerability, or a compromised third-party API response. If a connector held the platform’s real HubSpot API key or GitHub App private key directly, a single flaw in connector code could leak that credential, and the leak would be reusable by whoever obtained it, for as long as the credential remained valid. Credential isolation removes that exposure at the architecture level: even a fully compromised connector can only ever hand an attacker a credential that is already spent, or one that is about to expire in seconds and is bound to an authorization that has already been consumed.

​
How it works

The mechanism lives in packages/execution-control/src/, specifically two classes: SessionCredentialVault (SessionCredentialVault.ts:18-25) exposes three operations: issue(), consume(), and revoke(). Its in-memory implementation, InMemorySessionCredentialVault, wraps an underlying CredentialVault (the thing that actually holds the real, long-lived secret) and never itself stores the secret value. The class’s own doc comment states this precisely: “issue() only confirms the underlying credential exists, it never resolves or stores the secret” (SessionCredentialVault.ts:44-46).
  • issue(connectorId, authorizationId) calls credentials.getCredential(connectorId) once, purely to confirm a credential exists for that connector, then discards the resolved value immediately. It returns a SessionCredential object (SessionCredentialVault.ts:10-16) containing only an id, timestamps, and the connector/authorization it’s scoped to, never the secret itself.
  • consume(sessionCredentialId) is the only method that ever calls back into the underlying vault for the real value, and it does so fresh, at the moment of use. Before it does, it checks the session record for three failure conditions, each throwing if true: already revoked, already used, or expired (SessionCredentialVault.ts:97-111). It then marks the session used = true and returns the real credential exactly once. A second call to consume() on the same session id always throws.
  • revoke(sessionCredentialId) marks a session dead, unconditionally.
SessionCredentialSecureConnector (SessionCredentialSecureConnector.ts) is what actually wraps a real connector’s execute() call with this lifecycle. Its own execute() method (SessionCredentialSecureConnector.ts:74-131) does exactly this, in order:
  1. Asserts the connector’s policy allows this specific request (policy.assertAllowed(...)).
  2. Calls sessionCredentials.issue(...), obtaining a session credential id.
  3. Inside a try/finally: calls sessionCredentials.consume(...) to resolve the real credential just before use, passes it straight into the wrapped executor’s execute() call, and in the finally block, unconditionally calls sessionCredentials.revoke(...) , this runs whether the executor succeeded, threw, or the policy check itself threw after issuance.
  4. Records exactly one audit event, execution.completed or execution.rejected, naming the connector, the session credential’s id (never its value), the authorization it executed under, and the capability invoked. The credential’s id is auditable; the credential’s value never appears anywhere in the audit trail.
Because consume() throws on a second call, and revoke() runs unconditionally on every exit path via finally, a session credential can be used at most once, ever, no matter how the execution ends. One subtlety worth being precise about, from the class’s own doc comment (SessionCredentialSecureConnector.ts:20-32): this connector is also constructed with a gatewayAuthentication value proving it was configured with material signed by the Gateway’s key at registration time. That value is frozen once, at construction, and reused for every execution this connector instance will ever handle, it is not, and cannot be, a per-request proof by itself. The actual per-request replay protection comes from a different layer, ConnectorPolicy’s single-use GatewaySession check, enforced one level up, before a GatewaySession is even created. The two guarantees (registration-time authenticity, and per-request single-use) are deliberately separate mechanisms, not the same check reused twice.

​
How it enables things, with a concrete example

packages/api/tests/integration/credential-isolation.integration.test.ts proves this guarantee at the HTTP boundary, not just at the library level. Its own doc comment (credential-isolation.integration.test.ts:10-19) explains the split precisely: packages/execution-control/tests/unit/session-credential-secure-connector.test.ts already proves “a session credential is issued and destroyed exactly once per execution” by calling SessionCredentialSecureConnector.execute() directly; this integration test proves the exact same guarantee holds through a real POST /execute HTTP request against the real Express app, through the real ExecutionGateway / SessionCredentialExecutionControl / ExecutionControlService / SessionCredentialSecureConnector chain. It builds its own “inspectable” execution system (packages/api/tests/bootstrap/createInspectableExecutionSystem.ts) specifically to get a direct reference to the audit sink and the session credential vault, which the production bootstrap chain does not expose by design. The test asserts that after a successful /execute call, exactly one execution.completed audit event carries a credentialId, confirming a session credential really was issued and consumed, not skipped. packages/api/tests/integration/execution-failure.integration.test.ts is the companion case: it proves the same revoke-on-every-exit-path guarantee when the underlying connector executor throws, not just on the success path.

​
How to validate this yourself

  • packages/execution-control/src/SessionCredentialVault.ts and SessionCredentialSecureConnector.ts, the actual mechanism.
  • packages/execution-control/src/types.ts, CredentialVault, ExecutionCredential, SecureConnector, ConnectorPolicy interface shapes.
  • packages/execution-control/tests/unit/session-credential-vault.test.ts, session-credential-secure-connector.test.ts, session-credential-execution-control.test.ts , the library-level proofs, one per class.
  • packages/api/tests/integration/credential-isolation.integration.test.ts and execution-failure.integration.test.ts, the HTTP-boundary proofs.
  • packages/api/tests/bootstrap/createInspectableExecutionSystem.ts, how a test gets a direct handle on the audit sink and vault that production code never exposes.

​
Integration requirements

None from an operator’s perspective, this is an internal architectural guarantee, not a configurable feature. A new connector wired into this system automatically gets session credential isolation by virtue of being registered behind SessionCredentialSecureConnector; there is no opt-out path documented in the source, and none should be added without a strong, explicit reason.