Native credential execution in Spaces

Status: implementation and rollout runbook, September 8, 2026. The roles, access, and activity improvements shipped in PR #367. The operator has approved one Spaces deployment with Infisical remaining the secret store. Production cutover is explicit; existing external deployments retain compatibility until CREDENTIAL_EXECUTION_MODE=native is enabled.

Target

Human session / agent Commons identity
                 |
                 v
Spaces server: roles, assignments, connection policy, approvals
                 |
                 v
Internal executor: validate request, check live authority, consume once
                 |
                 +----> Infisical: retrieve the exact permitted secret
                 |
                 +----> Approved provider: inject credential for this call
                 |
                 v
Spaces database: redacted execution history and replay protection

The operator runs the existing Spaces service and database. Infisical stores and versions secrets. Agents continue using Commons APIs/MCP, receiving bounded provider responses rather than secret values. Credential pages and activity remain in Spaces. No standalone gateway, Infisical proxy container, or gateway audit database is required in the final deployment.

Reuse and changes

Area	Retain	Change
Identity and access	Human sessions, per-Space roles, agent assignments and grants, last-Owner guard	Keep the existing authority functions as the single policy source
Credential storage	Infisical paths, IDs, values, rotation history; existing write adapter	Add a narrowly scoped read adapter for internal execution
Execution	Destination/method/path/header limits, DNS/SSRF checks, response/time limits, live revocation	Extract gateway core from its HTTP server; call it inside Spaces
Tickets and approvals	Request binding, expiry, atomic one-use consumption, exact approval fingerprints	Store consumption with Spaces persistence; retain compatibility routes during migration
Activity	Agent/task/run attribution, redaction, filtered history	Write directly to Spaces tables and remove the audit-reader HTTP hop
Operations	Readiness and synthetic conformance checks	One service readiness surface, one release, fewer inter-service keys and URLs

Implementation: packages/credential-gateway/src/core.ts is a transport-free library shared by both modes. packages/api/src/credential-execution.ts binds it to live Spaces authorization, exact database credential references, the Infisical reader, and the existing Spaces database. No gateway process is started in native mode. The writer remains in infisical-writer.ts. Infisical supports a machine identity exchanging its client credentials for a short-lived API token, then retrieving an individual secret by name. Reuse the deployment’s configured Infisical region/domain; don’t hardcode a new region. See Universal Auth and secret retrieval.

Security tradeoff

The legacy gateway uses a proxy identity without value-read permission; the separate Infisical proxy handles injection. Removing both processes means the Spaces executor will hold retrieved values transiently. Infisical still handles storage, but compromise of the Spaces process can then reach the configured read scope. An internal module is not a process isolation boundary. Use a separate runtime read identity limited to the required environment and paths; retain the write identity’s existing scope. Do not grant broad vault read/list/admin rights. The operator approved this tradeoff on September 8, 2026. Reuse the scoped proxy reader identity during cutover; keep reader and writer identities separate. Never return values through metadata/reveal APIs, place them in agent environments, persist them in Spaces, or log request headers/bodies. Drop secret references promptly; JavaScript cannot guarantee memory zeroization. Keep outbound requests bounded and redirects disabled. Authentication injection must happen only after server-derived destination and live access checks. Block request overrides of destination, secret reference, and protected headers. Guard provider responses against credential reflection and keep error messages allowlisted. Vault and authorization outages fail closed. Do not retry an ambiguous provider mutation automatically.

Configuration

Native execution is the default on a fresh host. A pre-existing CREDENTIAL_GATEWAY_URL preserves external mode until the operator explicitly sets CREDENTIAL_EXECUTION_MODE=native. Unknown modes fail closed. Configure the Spaces API environment:

CREDENTIAL_EXECUTION_SIGNING_KEY: a new random signing secret, at least 32 characters. Use a different key from the retired gateway so old tickets cannot cross into the new replay store.
COMMONS_CREDENTIAL_DESTINATIONS_JSON: the existing destination allowlist (HTTPS origins, methods, path prefixes, allowed caller/response headers, timeout, and response size). Provider authentication headers must not be allowed as caller headers.
COMMONS_CREDENTIAL_BINDINGS_JSON: exact Space/connection/destination bindings to credential IDs already in Spaces. Header names are lowercase; the prefix is literal, including any trailing space. For example:

[
  {
    "space": "team-science",
    "connectionId": "team-science-publisher",
    "destinationId": "railway-team-science",
    "credentials": [
      { "credentialId": "railway-deploy", "header": "project-access-token", "prefix": "" }
    ]
  }
]

INFISICAL_READER_CLIENT_ID / INFISICAL_READER_CLIENT_SECRET: the dedicated runtime reader identity, limited to the referenced environment and paths.
Existing INFISICAL_DOMAIN, INFISICAL_PROJECT_ID, INFISICAL_ENVIRONMENT, writer identity, connection policies, and credential definitions remain.

Bindings select database credential IDs. Callers cannot submit vault paths, secret names, injection headers, or a different destination. Every credential on a connection must be active and bound; rotation reads its current value for the next call. Secret imports and reference expansion are disabled. POST /v0/spaces/:space/credential-calls and MCP call_external_service retain their contracts. Low-level ticket clients use the returned gateway_url, which now points to POST /v0/credential-execution/call on the Spaces host. The legacy field name is retained for client compatibility. Tickets are bound to the complete request and consumed atomically before external execution. There is no automatic retry or fallback between execution modes. Readiness is included in /healthz as credentials: {mode, configured, ready}. A configured native executor with invalid configuration or unavailable persistence makes readiness fail. An unconfigured fresh host can still run Spaces. Readiness does not fetch vault values; each execution fails closed on vault or authorization failure. The credential page derives its Spaces service on Railway link from Railway’s own service environment metadata.

History and cutover

credential_execution_events and credential_execution_ticket_uses live in the existing Spaces database. Execution events omit request paths, headers, bodies, secret values, and provider-controlled request IDs. History imports retain the old sanitized records, timestamps, source sequence and digest. The authorized UI projection omits sensitive internals in either mode and sorts by occurrence time, so importing older records does not hide new calls.

Deploy this code in existing external mode. Build the API, then run the operator-only migration command inside the Spaces deployment with its DATABASE_URL, old CREDENTIAL_GATEWAY_URL and read-only CREDENTIAL_GATEWAY_AUDIT_READER_KEY:
CREDENTIAL_HISTORY_SOURCE=railway-gateway-0ef2a619 node packages/api/dist/migrate-credential-history.js
The importer validates ordered pages, runs each page transactionally, and deduplicates by (source, source_sequence). A changed digest for an existing source sequence fails the import. It prints counts only and is safe to retry.
Set the native variables, preserving all existing connection allowlists, credentials and grants, then redeploy Spaces. Verify native readiness, allowed read-only fixture calls, request substitution denial and replay rejection. Verify per-Space and per-agent history remains available.
Drain legacy tickets for their configured maximum TTL plus request timeout. Run the history import again and verify a repeated import adds zero rows. Compare source counts and original timestamps before retiring the source.
Remove the gateway and proxy deployments and stop the old audit database runtime. Preserve the old database volume for rollback/retention. Remove obsolete CREDENTIAL_GATEWAY_* variables from Spaces and redeploy with only the native configuration.

Rollback before retirement may explicitly restore external mode and its old configuration. Do not reuse signing keys across the two stores or reissue an ambiguous provider write. After retirement, recover the old database/runtime before selecting external mode. Infisical values and versions are unchanged.

Verification

Tests cover native API issuance/execution, concurrent replay, exact approvals, live grant/membership/task/credential checks, cross-Space isolation, exact Infisical path/name retrieval, vault failure, protected headers, DNS/SSRF, redirect refusal, compressed response limits, total timeout, secret reflection, durable activity and idempotent history import. The same core also runs the standalone gateway suite. Local-calendar timestamps cover Today, Yesterday, weekday/month/day, relative age, year boundaries and daylight-saving changes.

Start

Work in a Space

Run continuously

Reference and operators

CREDENTIAL INTEGRATION PLAN

Native credential execution in Spaces

Target

Reuse and changes

Security tradeoff

Configuration

History and cutover

Verification

​Native credential execution in Spaces

​Target

​Reuse and changes

​Security tradeoff

​Configuration

​History and cutover

​Verification

Native credential execution in Spaces

Target

Reuse and changes

Security tradeoff

Configuration

History and cutover

Verification