Cloud integrations

Status: planned PermDock Cloud has an Integrations page where an environment is connected to the platforms around it: identity providers, Vercel, observability backends, SIEMs, webhooks, compliance platforms, your own database, chat surfaces and an MCP host. This page is the contract for that UI. It fixes what each connector speaks; the PermDock-Cloud repository implements it. Two rules from the rest of the docs apply to every row (adapters, PermDock Cloud, invariant 15):

• A connector is a standard wire format (AuthZEN, OCSF, CloudEvents, OTLP, SCIM, CAEP, JOSE, OIDC) or an existing PermDock interface (ApprovalStore, DecisionSink, SnapshotSource, DirectoryStore). There is no permdock/auth0, permdock/datadog or permdock/vanta, and connecting a platform never adds a dependency to your application.
• No connector sits on the decision path. Inbound connectors change who the Cloud authenticates, what your DirectoryStore contains, or (in Cloud-native directory mode) which claims the Cloud mints into the tokens your app verifies; outbound connectors copy evidence and notifications out. Nothing any connector does is consulted by can, decide, filter, where or simulate.

Each table below has the same columns. Connector is what the Integrations page shows. Standard or interface is the only thing the connector speaks. What it carries is the data that crosses. Never is the thing the connector is not allowed to do, and each of those is a row in the threat model.

Inbound: identity providersCopy Anchor Link

One identity provider can be connected in up to four roles. They are independent: a tenant may use Okta as a SCIM source while its end users authenticate with Clerk.

The environment's directory mode decides which rows apply. In Cloud-native mode the Cloud directory is the source of the claims it mints, and upstream providers connect only as federated login. In bring-your-own mode your provider or your tables stay authoritative: end users either log in through the Cloud issuer, which federates to the provider, or bypass the Cloud entirely and your app uses the provider's subjectFrom*; the SCIM relay feeds your DirectoryStore.

"Connect Supabase" on the identity side means Supabase Auth as a trusted issuer (its project JWKS, role and app_metadata handled as on the Supabase adapter page); the Cloud never reads your Supabase tables or RLS policies. "Connect Clerk", "Connect Auth0" and "Connect WorkOS" mean the same three roles with the provider's discovery URL, SSF transmitter and SCIM client.

Inbound: VercelCopy Anchor Link

The Vercel connector is already specified on the Cloud adapter page ("Vercel Marketplace" and "Hosted Authorization Decision Service"); the Integrations page links those sections rather than duplicating them.

Outbound: observability (OTLP)Copy Anchor Link

Because the attribute names are the same set permdock/otel emits from inside your application, a backend cannot tell an app-side span from a Cloud-side log record, and one dashboard serves both.

Outbound: SIEM (OCSF)Copy Anchor Link

Outbound: webhooksCopy Anchor Link

Webhooks are the generic escape hatch: anything not listed on this page receives CloudEvents over HTTP.

A receiver verifies the JWS against the environment's JWK Set, <PERMDOCK_CLOUD_URL>/v1/environments/<env>/.well-known/jwks.json (cloudEndpoints().jwks from permdock/cloud), with aud equal to itself and exp; the batch jti and each event id make replay detectable. Retries use exponential backoff with the same jti and id, so a receiver deduplicates on them. A TypeScript receiver uses verifyWebhook from permdock/cloud; any other language uses its JOSE library the same way.

import { cloudEndpoints, verifyWebhook } from "permdock/cloud";
import { memoryReplayStore } from "permdock/ssf";

const replay = memoryReplayStore();

export async function POST(request: Request) {
  const delivery = await verifyWebhook(request, {
    jwks: cloudEndpoints().jwks,
    audience: "https://app.example.com/api/permdock-webhook",
    replay,
  });
  if (!delivery.ok) return new Response(null, { status: 401 });
  for (const event of delivery.events) {
    if (event.type === "dev.permdock.catalog" && event.data.kind === "publish")
      await permdockCloud.policies.refresh();
  }
  return new Response(null, { status: 204 });
}

verifyWebhook never throws. It answers { ok: false, reason } with unsigned (the body is not a compact JWS), invalid-token (with the verifier's cause), invalid-events (an event outside the closed type list, a data shape that does not match its type, or a __proto__, constructor or prototype key) or replayed (a jti the ReplayStore already holds). parseCloudEvent is the same per-event check for events read from a queue.

Signed only, because a webhook receiver is usually a public URL. An unsigned mode with a shared secret or an optional HTTP signature would be the mode everyone ships first, and a forged catalog or membership event then triggers a refresh or an alert on attacker input. The batch reuses the decision-export envelope so a receiver has one typ, one key set and one verifier for everything the Cloud sends.

Outbound: compliance evidenceCopy Anchor Link

Outbound: data destinationsCopy Anchor Link

This is how "connect Supabase" reads on the data side: Supabase is a destination that receives evidence, not a source the Cloud queries.

Outbound: approval deliveryCopy Anchor Link

Outbound: MCPCopy Anchor Link

What the page does not offerCopy Anchor Link

• A connector that resolves memberships or roles from a provider API. That is a MembershipSource or RoleSource in your application, or SCIM into a DirectoryStore you own (tenancy, invariant 15).
• A connector that pushes a policy into the application. Policies are code in your bundle; permdock cloud push publishes a copy to the hosted ADS and the catalog, in one direction.
• Per-vendor npm entries or per-vendor OpenAPI extensions.
• An authentication product or a gateway. Trusted issuers are how the Cloud consumes authentication, not how it provides it.
• An MCP explain tool that evaluates a permission for a subject. Explaining a past decision needs no evaluation: the stored event already carries matched, via and denials, and the evidence query tool returns it. Evaluating a hypothetical one would make the Cloud's MCP server take a subject as an argument, which invariant 13 forbids, and would answer from the pushed copy of the policy rather than the code the application runs. What-if questions belong to simulate in the application or a describePolicy test.

Example appCopy Anchor Link

No example app of its own: apps/examples/eve-agent (the Marketplace template) exercises the Vercel, Slack and evidence-export connectors against a Cloud environment; apps/examples/scim exercises the SCIM relay.

Related standardsCopy Anchor Link

• OpenID Connect, JOSE and JWT authorization claims: trusted issuers.
• Shared Signals and CAEP: CAEP transmitters.
• SCIM 2.0: SCIM sources and the relay.
• MCP authorization: the Cloud's MCP server.
• Wire formats: CloudEvents types, the OCSF projection and permdock-decisions+jwt.
• adapters, PermDock Cloud.