> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polycore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security model

> Credential custody, least privilege, trust boundaries, and the security assumptions behind Polycore.

Polycore is designed around a narrow security objective: let humans and agents
request production operations without giving those callers the underlying
execution credentials.

The customer-hosted runner holds the scoped authority for private systems. For
supported shared SaaS resources, a separate private integration executor holds
an encrypted provider grant and exposes only fixed, bounded adapters. The
Polycore control plane governs both paths and records what happened.

## Credential custody

<Columns cols={3}>
  <Card title="Runner credentials" icon="server-cog">
    Database passwords, service-account authority, and private API keys live in
    your infrastructure. The runner resolves them through workload identity or
    your deployment's secret injection.
  </Card>

  <Card title="Hosted provider grants" icon="lock-keyhole">
    Shared SaaS installation tokens are encrypted with KMS-backed envelope
    encryption in a separate private executor. The public control plane stores
    only safe grant metadata and an opaque credential id.
  </Card>

  <Card title="Caller credentials" icon="badge-check">
    Slack identities, web sessions, and MCP authentication authorize requests to
    Polycore. They do not provide direct access to your database, cloud project,
    or API.
  </Card>
</Columns>

Execution secrets are not:

* Sent to callers, agent prompts, tool schemas, Slack, MCP clients, or dashboard pages.
* Stored in public control-plane metadata tables or capability-invocation rows.
* Accepted by arbitrary provider URLs or generic HTTP operations.
* Committed to the runner repository.

Hosted provider grants are decrypted only inside the isolated executor. The
executor uses a fixed provider adapter, least-privilege service IAM, bounded
request and result schemas, provider-host allowlists, rate limits, and a
credential deletion path. A provider response is untrusted data and cannot
change tool policy, environment routing, approval state, destination, or
source generation.

<Info>
  Polycore reduces credential exposure, but the runner host remains a sensitive
  workload. A compromise of that host or its runtime identity can reach whatever
  its downstream permissions allow.
</Info>

## Defense in depth for reads

Generic reads use two independent enforcement layers.

<Steps>
  <Step title="Layer 1: downstream least privilege">
    The datastore enforces a read-only identity, such as a Postgres role with
    `SELECT` grants or a GCP service account with `roles/datastore.viewer`.
  </Step>

  <Step title="Layer 2: constrained runner implementation">
    The runner exposes read operations only. Postgres executes inside a
    read-only transaction. Firestore query capabilities call read APIs only.
  </Step>
</Steps>

Both layers should be present when the platform supports them. If one is
misconfigured, the other still narrows what the generic query path can do.

Writes are a separate opt-in per family. Prefer `"write": "ambient"` (ADC)
when the runtime SA already writes, as on CIP/SAP. Prefer
`"write": { "keyEnv": "…" }` when you want Layer 1 to stay viewer-only on the
runtime SA; widening that identity to unlock writes would remove Layer 1 from
every read at once.

<Columns cols={2}>
  <Card title="Postgres" icon="database" href="/integrations/postgres">
    Read-only role or replica, read-only transaction, statement timeout, query
    planning, and a 1,000-row result cap.
  </Card>

  <Card title="Firestore" icon="flame" href="/integrations/firestore">
    Viewer IAM, read-only SDK methods, bounded document queries, and server-side
    aggregations.
  </Card>
</Columns>

## Controls for writes

A durable write capability has several boundaries:

<Columns cols={2}>
  <Card title="Reviewed definition" icon="git-pull-request-arrow">
    Action code, input and output schemas, hazard, and secret declarations live
    in your repository and reach production through your deployment process.
  </Card>

  <Card title="Explicit hazard" icon="shield-alert">
    Actions default to `write` when no hazard is declared. The control plane
    feeds that metadata to your access policy, which can hold the request before
    dispatch.
  </Card>

  <Card title="Human decision" icon="user-check">
    Agent and member requests remain pending in an out-of-band approval surface.
    Direct owner or admin web actions can record self-approval inline.
  </Card>

  <Card title="Scoped credential" icon="key-square">
    The action receives only its declared local secrets and should use a
    credential restricted to the operation it performs.
  </Card>
</Columns>

These controls serve different purposes. Code review governs standing
authority. Runtime approval governs one use of that authority. Downstream IAM
limits the final blast radius.

## Delegated code

An explicitly configured runner can advertise `code.execute`, which runs one
approved workload in a disposable container on the runner host. Its hazard is
`unknown`, so it always remains pending for human review and never uses inline
web self-approval.

The runner enforces a read-only root filesystem, dropped Linux capabilities, no
network unless requested, process and resource caps, a wall-clock timeout, and
injection of only the secret keys requested by the workload.

<Warning>
  Delegated code is an opt-in preview surface, not part of the default first
  integration. Enabling it materially expands the runner's execution surface.
  Review the base image, OCI runtime, egress, dependency installation, secret
  requests, and host isolation before advertising `code.execute`.
</Warning>

## Trust boundaries and failure impact

<AccordionGroup>
  <Accordion title="A caller credential is compromised" icon="user-x">
    An attacker may request capabilities visible to that caller. They still do
    not receive execution credentials. Read and write behavior remains subject
    to the configured Polycore path, including the approval record for writes.
  </Accordion>

  <Accordion title="An agent prompt is manipulated" icon="bot">
    The model can choose among its advertised capabilities and arguments. It
    cannot invent a capability the runner did not advertise, and a requested
    write still enters pending approval. Read access must therefore be scoped
    carefully because reads do not require approval.
  </Accordion>

  <Accordion title="The control plane is compromised" icon="cloud-off">
    The control plane is an authorization authority and holds runner enrollment
    and signing material plus the private executor's caller token. A full
    compromise could submit governed requests, invoke the executor within its
    typed catalog, or expose audit data, but it does not receive the decrypted
    provider grant. The isolated executor's service identity, KMS permissions,
    fixed provider adapter, and kill switch remain separate controls.
  </Accordion>

  <Accordion title="The runner host is compromised" icon="server-off">
    The attacker may gain the runtime identity, locally available action
    secrets, and network reach assigned to that runner. This is why one runner
    serves one environment, identities are least-privilege, and the host belongs
    inside your existing cloud security boundary.
  </Accordion>

  <Accordion title="A downstream credential is over-privileged" icon="key">
    The runner's constrained query implementation still blocks generic writes,
    but custom action code can use the authority it receives. Review action
    definitions and separate read and write credentials rather than relying on
    runner policy alone.
  </Accordion>
</AccordionGroup>

## Data that reaches Polycore cloud

The control plane needs enough information to govern and explain operations. It
stores or processes:

* Organization, project, environment, and runner metadata.
* Capability names, descriptions, hazards, and JSON schemas.
* Optional project context advertised by the runner.
* Caller requests and agent responses.
* Capability arguments, outcomes, and timing. Runner results are size-bounded;
  hosted-integration audit rows keep a content-free shape summary rather than
  provider content.
* Approval requests and decisions.
* Dashboard page source and compiled artifacts when dashboards are in use.

It does not need your database connection string, service-account key, or
private API secret. For a hosted direct integration, the executor receives the
provider token, while the control plane receives only safe workspace identity,
capability, routing, and status metadata.

<Warning>
  Query results and action outputs may themselves contain sensitive customer
  data. During integration, define bounded outputs, avoid returning secret
  fields, and decide which data should be redacted before it crosses from the
  runner to the control plane.
</Warning>

## Network and dispatch integrity

<Columns cols={2}>
  <Card title="No inbound runner port" icon="shield">
    The runner initiates its TLS WebSocket to Polycore. Customer firewalls do
    not need to accept an internet-originated connection to the runner.
  </Card>

  <Card title="Signed envelopes" icon="file-key">
    The control plane signs each dispatch with runner-specific signing material.
    The runner verifies the signature before resolving credentials or executing
    the capability.
  </Card>
</Columns>

Transport protection and signed envelopes protect the connection path. They do
not replace caller authentication, approval, capability review, or downstream
IAM.

## Audit properties

Audit records are written by the control-plane runtime as part of the request
path, so individual action implementations do not decide whether to log.
Requests, invocations, approvals, failures, and denials are linked in one
persistent model.

<Note>
  The current audit store is centralized and durable. It should not be described
  as cryptographically immutable or tamper-evident. If your compliance model
  requires external retention or SIEM export, include that requirement in the
  integration scope.
</Note>

## Security review during integration

We review the following with your team before production validation:

<Check>Runner placement, outbound routes, and downstream network access.</Check>

<Check>
  Read and write identities, IAM grants, and secret rotation ownership.
</Check>

<Check>Every advertised capability, schema, hazard, and declared secret.</Check>

<Check>
  Sensitive fields in arguments, outputs, project context, and audit records.
</Check>

<Check>Approval surfaces, denial behavior, and failure reporting.</Check>

<Check>
  Environment isolation and the process for reviewing catalog changes.
</Check>