The Gateway

The sole boundary through which Parmana releases approved execution requests to connectors. Wired into the default server unconditionally, as of commit 651497a.

[AVAILABLE]. packages/execution-gateway, 25 tests.

This page corrects a claim this site made through 2026-07-08: earlier material says the gateway is “a library you wire in, not a default,” and that a stock packages/api server gets no content-binding enforcement. That was true then. As of commit 651497a (2026-07-11), packages/api/src/bootstrap/createExecutionSystem.ts unconditionally returns createExecutionGateway(), there is no server code path that skips it. See Quickstart for a verified live run.

What it is

ExecutionGateway is the sole boundary through which a signed execution authorization actually results in something running. It does not trust the authorization it’s handed: it independently re-verifies the envelope and re-derives the content hash itself before anything reaches a connector.

Why it exists

An authorization envelope proves that Parmana decided to approve something. It doesn’t by itself stop a receiving system from executing something else under that approval, or from skipping verification altogether. The gateway is the one place designed to say no even if every earlier stage said yes: the last point before a real system state changes.

How it behaves

ExecutionGateway implements @parmana/execution-system’s ExecutionSystem interface, so it plugs into RuntimeFactory.create() exactly like any other execution system, no change to RuntimeEngine or RuntimePipeline is required to use it. It composes @parmana/envelope-verifier’s checks (version, signature, expiry, TTL, nonce) and adds exactly one more: recomputing the executable content hash and comparing it to businessTransactionHash.

// packages/execution-gateway/src/ExecutionGateway.ts:150-165
if (passed) {
  const actualHash = await this.contentHasher.hash(executableContent);
  const expectedHash = request.authorization.payload.businessTransactionHash;

  businessTransactionHashMatches = actualHash === expectedHash;

  if (!businessTransactionHashMatches) {
    hashMismatch = { expected: expectedHash, actual: actualHash };
  }
}

Check order, side-effect-free checks first (ExecutionGateway.ts:86-90):

version → signature → expiry → TTL policy → businessTransactionHash recompute-and-compare → nonce

The nonce (single-use) check runs last, and only if every prior check, including the content hash, passed. This matters: a forged or mismatched request must never burn a nonce, or an attacker who observes a nonce in transit could poison it and get the legitimate request rejected instead (ExecutionGateway.ts:170-180).

ExecutableContentHasher delegates to the same TrustRecordHasher used elsewhere in the system (packages/crypto/src/ExecutableContentHasher.ts), the signing side and verifying side run identical canonical serialization and hashing, never two parallel implementations of the same computation.

Nonce single-use is scoped to whichever NonceStore instance checks it. Multiple independent gateway instances each using their own MemoryNonceStore can each accept the same authorization once. Fleet-wide single-use requires one shared store (CLAIMS.md 3.2).

Minimal example

const gateway = new ExecutionGateway({
  publicKey,          // Parmana's public key
  nonceStore,          // shared across instances for fleet-wide single-use
  connector,           // e.g. new HttpConnector({ baseUrl, headers })
  // or: executionControl: { service: executionControlService, route }
});

const application = createApplication(gateway); // wires it into RuntimeFactory.create()

The default server’s own bootstrap (packages/api/src/bootstrap/createExecutionGateway.ts) follows this exact shape, using executionControl rather than a direct connector, see Credential isolation.

Connectors: what’s actually wired today

A Connector is what the gateway hands verified, frozen content to after every check passes. HttpConnector and MockConnector are reference implementations in @parmana/connector-sdk. Two real, production-registered connectors exist: razorpay (whenever RAZORPAY_KEY_ID/RAZORPAY_KEY_SECRET are configured) and hubspot (whenever HUBSPOT_PRIVATE_APP_TOKEN is configured), each making genuine external API calls, not scripted responses. Four enterprise-named mocks also exist in the codebase (packages/connector-sdk/src/connectors/{sap,oracle,workday,salesforce}/), each an explicit MockConnector wrapper, self-documented as “deterministic, in-memory, used until the real enterprise connector is implemented.” These are reference mocks, not integrations, are never registered by packages/api/src/bootstrap, and should not be represented as SAP, Oracle, Workday, or Salesforce connectivity.

Update (Phase 2A), historical record, superseded below: vendor-payment (packages/api/src/bootstrap/createVendorPaymentConnector.ts) previously registered a MockConnector unconditionally, including in production — see the production certification and fix for why that was a trust gap. Phase 2A made it register only when NODE_ENV=test; in production, no connector backed payments:execute from that point on, and it failed closed with the same "No connector registered for capability" error any other unregistered action gets.

Final update (2026-08-09): payments:execute/vendor-payment was never on the product roadmap as a real capability, so rather than building the independent signal verification that would have been required to keep it, it was removed from the repository entirely — createVendorPaymentConnector.ts no longer exists, in any form, in any environment. See docs/VERIFICATION-GAPS.md G-27 in the source repository. A generic, NODE_ENV=test-only connector (createTestFixtureConnector.ts, capability test:fixture-execute) now serves the narrow role of giving this repository’s own shared test fixtures something to execute against; it is internal test scaffolding, not a product feature, and is not documented further here.

Adding a real connector to the running server is a bootstrap code change today (createConnectorRegistry.ts, createConnectorAuthenticator.ts), not configuration. See Add a connector with the Connector SDK.

Failure reporting

ExecutionGateway.execute() throws on any failed check, naming every failing check and, on a content mismatch, both hashes:

Execution Gateway rejected request: failed checks [businessTransactionHashMatches].
businessTransactionHash mismatch: expected <hash>, got <hash>.

(ExecutionGateway.ts:250-265, describeFailure.)

Next

Gateway attestation

The gateway’s own signature: what it proves about a release, and what it doesn’t.

Credential isolation

What happens to the credential a connector needs, once the gateway releases execution.