Custom Provider

​

What You Build

1. You implement the endpoints below on an HTTPS base URL you control.
2. In CloudCruise you add a Custom provider connection and point it at your base URL.
3. You bind vault credentials to items in your password manager by their ref, your own item identifier.
4. When a workflow needs the credential, CloudCruise calls POST /v1/items/resolve and uses the returned username, password, and TOTP seed.

​

Creating a Connection

1. Navigate to Workspace Settings → Integrations.
2. In the Secret Providers section, add a Custom provider connection.
3. The dialog generates a random signing secret (64 hexadecimal characters, as for webhooks) and shows it before the connection exists. You can replace it with your own secret in the same format, generated from a cryptographically secure random source (for example openssl rand -hex 32). Prefer one secret per connection.
4. Deploy the signing secret on your side first.
5. Enter a connection name, your base URL, and a Cache duration (see Caching and call volume), then click Connect.

​

Request Authentication

<X-CloudCruise-Timestamp>
<X-CloudCruise-Request-Id>
<X-CloudCruise-Connection-Id>
POST
<endpoint path, e.g. /v1/items/resolve>
<lowercase hex SHA-256 of the raw request body bytes>

• Compute the body hash over the raw bytes you received, before any JSON parsing. Re-serialized JSON will not match.
• Accept the request if any v1= value in the signature header matches, compared in constant time.
• Reject requests whose timestamp is more than 300 seconds away from your clock, in either direction. Keep your server time synchronized (NTP).
• Serve over HTTPS with a publicly trusted certificate. Plain HTTP and self-signed certificates are rejected by CloudCruise.

​

Hardening checklist

• Keep the signing secret in a secret manager or in environment configuration, never in source control. Do not reuse it for anything else, including your webhook secret.
• Never log request or response bodies. resolve responses carry passwords and one-time-code seeds. Log the connection id, request id, endpoint and status only.
• Limit how many bytes of the request body you read before hashing it. CloudCruise’s requests are small.
• Give each CloudCruise connection its own signing secret, and answer 403 forbidden for any item that connection should not read, so a connection can only resolve what you intend it to.
• Rotate the signing secret as soon as you suspect it was exposed (see Rotating the Signing Secret).

​

Example verification (Node.js)

import crypto from "node:crypto"

// rawBody is the exact bytes received (a Buffer read with a size limit), not JSON.stringify(req.body).
function verify(req, rawBody, secret, endpointPath) {
  const tsHeader = String(req.headers["x-cloudcruise-timestamp"] ?? "")
  const ts = Number(tsHeader)
  if (!/^\d+$/.test(tsHeader) || Math.abs(Date.now() / 1000 - ts) > 300) return false
  const requestId = String(req.headers["x-cloudcruise-request-id"] ?? "")
  const connectionId = String(req.headers["x-cloudcruise-connection-id"] ?? "")
  if (!requestId || !connectionId) return false
  const bodyHash = crypto.createHash("sha256").update(rawBody).digest("hex")
  const signed = [tsHeader, requestId, connectionId, "POST", endpointPath, bodyHash].join("\n")
  const expected = crypto.createHmac("sha256", secret).update(signed).digest()
  return String(req.headers["x-cloudcruise-signature"] ?? "")
    .split(",")
    .map((part) => part.trim())
    .filter((part) => part.startsWith("v1="))
    .slice(0, 2)
    .some((part) => {
      const given = Buffer.from(part.slice(3), "hex")
      return given.length === expected.length && crypto.timingSafeEqual(given, expected)
    })
}

​

Test vector

​

Item References

​

Binding credentials

​

Two-Factor Authentication (TOTP)

​

Caching and Call Volume

• for one credential, when its binding or settings are edited,
• for the whole workspace, when connection settings change or a user clicks Clear cached secrets in Workspace Settings → Integrations.

• when a run is submitted for a specific credential, to check that it resolves,
• every time a run is handed to a browser, including after a requeue,
• when a user opens the credential in the dashboard, or an API client reads it through the Vault API,
• occasionally while CloudCruise analyses a failed run.

• several runs start at once while the cache is empty; each may call resolve,
• a call failed, or returned none of the three values; such results are not cached, so the next run calls again.

​

What CloudCruise holds, and for how long

• The cache is shared by all runs of the workspace, kept per credential, and encrypted with the workspace’s key. It never outlives the cache duration.
• A run gets the credential’s values each time it is handed to a browser and holds that copy while it runs and for up to 30 minutes after it ends. A requeued run is handed to a browser again and picks up the current values. Changing or revoking the item affects runs handed to a browser afterwards (once the cache expires or is cleared), not runs already in progress.
• When your service is unavailable, runs keep using a cached value until it expires. After that, a run submitted for a specific credential is rejected, and a run that is already queued fails when it is handed to a browser (temporary failures requeue it). There is no stale fallback beyond the cache duration.
• A cache duration of 0 means CloudCruise resolves the item for every run. The run still holds its copy as described above, and the browser running the workflow receives the values it has to type.
• Two separate authorizations. Your endpoint decides whether CloudCruise may obtain a secret from you. CloudCruise’s own access control decides who may use a secret CloudCruise has obtained: runs of the workspace, its members, and its API keys.
• Revoking access. Revoking the signing secret or removing the item’s access on your side stops CloudCruise from obtaining the secret again; clicking Clear cached secrets in CloudCruise removes the cached copies. Neither recalls copies already held by runs in progress, held for up to 30 minutes after a run ends, or read by API clients. Immediate revocation of every copy is not possible; change the password itself if it must stop working.

​

Timeouts, Retries, and Size Limits

• Answer promptly. CloudCruise gives each request a few seconds, so a slow answer is treated as a failure.
• On timeouts, connection errors, 429 and 5xx, CloudCruise retries a limited number of times within a short overall time limit. A Retry-After of up to 10 seconds is honoured. It never retries other 4xx responses.
• Every retry is a new request with a new id and signature, so make your handlers safe to call more than once.
• Responses larger than 64 KiB (list: 5 MiB) are rejected.

​

Network Rules

• The base URL must be HTTPS and its hostname must resolve only to public addresses. Private, loopback, link-local (including cloud metadata addresses) and other reserved addresses are rejected.
• CloudCruise checks the address it actually connects to on every request, not only when the connection is saved.
• Redirects are never followed. Any 3xx response is treated as an error. Configure the final URL as the base URL.

​

Errors

​

Rotating the Signing Secret

1. Add a second signing secret to the connection in CloudCruise (generated, or your own in the same format).
2. While both secrets are active, CloudCruise sends two signatures, comma-separated in X-CloudCruise-Signature. A connection has at most two active secrets, so the header never holds more than two v1= values; you may reject one that does.
3. Deploy the new secret on your side. Your verification accepts the request if any signature matches, so the old secret keeps working while you deploy.
4. Remove the old secret in CloudCruise.

​

Forward Compatibility and Versioning