@parmana/execution-control

Gateway-authenticated, session-scoped credential isolation for connectors. Also home to a separate, currently-unwired Execution Permit model, disambiguated below.

[AVAILABLE] for credential isolation, wired into the default server. [PARTIAL] for the separate ExecutionPermit model described below, real and tested, not reachable from packages/api or packages/runtime today.

Purpose

Authenticates a calling gateway, issues single-use session credentials, and routes a verified release to a connector, auditing every step. See Credential isolation and Gateway attestation for the concepts.

Install

npm install @parmana/execution-control

Key exports: the wired credential-isolation path

Export	Stability
ExecutionControlService	[AVAILABLE]. Authenticates a gateway, opens a session, routes to a connector, audits each step.
SessionCredentialExecutionControl	[AVAILABLE]. Wraps ExecutionControlService so no session can be created without a valid, request-bound gateway attestation.
GatewayAttestationSigner / GatewayAttestation	[AVAILABLE]. See Gateway attestation.
SignedTokenConnectorAuthenticator	[AVAILABLE]. Verifies a GatewayAttestation’s signature and that it’s bound to the request’s authorizationId.
SessionCredentialVault, InMemorySessionCredentialVault	[AVAILABLE]. Single-use, time-bounded credential leases. See Issue and verify session credentials.
SessionCredentialSecureConnector	[AVAILABLE]. Wraps a raw executor so it only runs after policy, attestation, and session checks all pass.
Clock, SystemClock, IdGenerator, RandomIdGenerator	[AVAILABLE]. See Determinism and clocks for their real, narrow scope.
MemoryExecutionAuditSink	[AVAILABLE]. In-memory only, records session.created / execution.completed / execution.rejected events.
ConnectorRegistry, ConnectorAuthenticator, CredentialVault, GatewaySessionStore, ConnectorPolicy, SecureConnector (interfaces)	[AVAILABLE]. The seams @parmana/connector-sdk implements.

A second, separate model in this package: ExecutionPermit

This is not the same thing as “Execution Permit,” an earlier prototype name for Execution authorization (packages/shared/src/domain/execution-permit.ts, added and deleted the same day, see the Glossary). That file is gone. This is a different, currently real, ExecutionPermit:

// packages/execution-control/src/models/ExecutionPermit.ts
export interface ExecutionPermit {
  readonly permitId: string;
  readonly artifactHash: string;
  readonly gatewayId: string;
  readonly policyVersion: string;
  readonly decision: ExecutionDecision;
  readonly issuedAt: string;
  readonly expiresAt: string;
  readonly signatures: SignatureBundle;
}

ExecutionPermitBuilder and ExecutionDecision (also exported from this package) build this artifact. It’s consumed by @parmana/receipt’s ExecutionReceiptBuilder, and exercised end to end by examples/tutorials/53-execution-permit/ through 56-complete-execution-flow/. Nothing in packages/runtime or packages/api imports @parmana/receipt or this ExecutionPermit model. It is real, tested, hybrid-signature-capable code, running in a parallel path the default server and the main Execution trust record pipeline never touch.

Minimal example

import { InMemorySessionCredentialVault, RandomIdGenerator, SystemClock } from "@parmana/execution-control";

const vault = new InMemorySessionCredentialVault({
  credentials, clock: new SystemClock(), idGenerator: new RandomIdGenerator(), lifetimeMs: 30_000,
});
const session = await vault.issue("hubspot", authorizationId);
const credential = await vault.consume(session.sessionCredentialId); // only once

Full runnable version: Issue and verify session credentials.

Next

Issue and verify session credentials

Issue, consume, expire, reuse-reject, and revoke, run live.

@parmana/receipt

The other half of the unwired ExecutionPermit path.