Building Secure Apps

Every cPod App runs inside the CyberPod platform trust boundary. The platform vouches for the caller's identity — tenant, user, install, and permissions — by signing each request with an HMAC-SHA256 context header. Your app must verify that signature before reading data, check write permissions before mutating EDM records, and emit audit events for every write.

This guide covers the security primitives you will use when building apps on the platform. The reference implementation lives in shared/platform-runtime/ in the app-store repo; this page explains why each primitive exists and how to use it correctly.

Platform Context#

Platform context is the identity payload that the CyberPod platform attaches to every request your app receives. It carries:

In production, the platform also attaches a cryptographic signature and a set of time-bound claims:

HMAC-SHA256 Verification#

The platform signs a canonical JSON payload built from the context fields and claims:

{
  "tenantId": "...",
  "userId": "...",
  "installId": "...",
  "permissions": ["edm.customer.read", "edm.customer.write"],
  "issuedAt": "...",
  "expiresAt": "...",
  "audience": "...",
  "nonce": "..."
}

Your app verifies the signature using the shared CPOD_CONTEXT_SIGNING_SECRET. The comparison uses timingSafeEqual to prevent timing attacks.

TTL, Audience, and Nonce Validation#

Signed contexts are validated against three temporal and identity constraints:

• TTL: The difference between expiresAt and issuedAt must not exceed CPOD_CONTEXT_MAX_TTL_SECONDS (default: 300 — five minutes). A clock skew of CPOD_CONTEXT_CLOCK_SKEW_SECONDS (default: 60) is tolerated.
• Audience: The audience claim must match CPOD_CONTEXT_AUDIENCE or CPOD_APP_ID. In production, a missing audience configuration causes verification to fail.
• Nonce: Must be present and at least 12 characters long.

Trust Modes#

getPlatformContext() returns a trustMode that tells you exactly why a context is or is not trusted:

Usage#

import { getPlatformContext } from '../../../shared/platform-runtime'
 
const context = await getPlatformContext()
 
if (!context.trusted) {
  // Render a clear error: context.trustMode tells you why
  return { error: `Untrusted context: ${context.trustMode}` }
}
 
// context.tenantId, context.userId, context.installId, context.permissions
// are now safe to use for EDM reads and writes

Governed Writes#

All EDM mutations follow a prepare → review → commit lifecycle. The governed write pattern ensures that no write reaches the EDM without passing validation, permission checks, and — when required — human approval.

The Three Phases#

1. Prepare — The app constructs a draft and validates it locally. The write gate checks permissions and context trust. If anything fails, the result is prepare_only: the draft is returned to the caller with validation errors, but nothing is written.

2. Review — For high-risk mutations, the commit flag is set to false and the draft is shown to a reviewer. The UI renders the diff, source citations, and reason before the user confirms.

3. Commit — The app calls applyEdmUpdate with commit: true. The write gate is re-checked, the SDK write is executed, and an audit event is emitted.

Input: AppGovernedUpdateInput#

Context: AppGovernedUpdateContext#

Result: AppGovernedUpdateResult#

Usage#

import { applyEdmUpdate } from '../../../shared/platform-runtime'
 
const result = await applyEdmUpdate(
  {
    domain: 'customer.accounts',
    recordId: 'customer.accounts/abc-123',
    draft: { status: 'active' },
    commit: true,
    reason: 'Account reactivated after payment received',
  },
  context,
)
 
if (result.writeMode === 'commit') {
  // Write succeeded — result.appliedAt has the timestamp
} else {
  // Write was prepared but not committed
  // result.validation.errors explains why
  // result.validation.warnings shows write gate issues
}

Write Gates#

Every governed write passes through validateWriteGate before reaching the SDK. The write gate is a permission and identity check — if it fails, the write is blocked and the result is prepare_only with the gate failures listed in validation.warnings.

What the Write Gate Checks#

The gate validates the following, in order:

1. Trusted context — context.trusted must be true. An unverified context cannot write to the EDM.
2. Tenant ID — context.tenantId must be present.
3. User ID — context.userId must be present.
4. Install ID — context.installId must be present.
5. Domain permission — The context's permissions array must contain the required write permission for the target domain.

Permission Map Pattern#

The required permission for a domain is resolved through a prefix-based permission map. Each app defines its own map in lib/edm.ts:

const permissionMap: Record<string, string> = {
  'customer.': 'edm.customer.write',
  'approvals.': 'edm.approvals.write',
  'projects.': 'edm.projects.write',
  'riskCompliance.': 'edm.riskCompliance.write',
}

When a write targets customer.accounts, the gate looks up the longest matching prefix (customer.) and requires edm.customer.write in the caller's permissions.

If no prefix matches, the gate falls back to a default: edm.{rootDomain}.write. For storage.files, the default would be edm.storage.write.

Gate Failure Is Non-Destructive#

When the write gate fails:

• The draft is preserved in result.diff — nothing is lost.
• result.writeMode is prepare_only.
• result.validation.warnings lists every gate failure (e.g. "Trusted or signed platform context is required for EDM writes.", "edm.customer.write is required for EDM writes.").
• No SDK call is made and no audit event is emitted.

This lets the UI render the draft for review, show exactly which permissions are missing, and offer the user a path to request access.

Audit Emission#

Every governed write — whether it succeeds or fails — emits an audit event through the CyberPod SDK telemetry service. Audit events give platform administrators a complete trail of who changed what, when, and why.

What Gets Emitted#

On a successful commit or a failed write attempt, applyEdmUpdate calls client.audit.emit() with:

Non-Blocking#

Audit emission is non-blocking: if the client.audit.emit() call fails, the write result is not affected. The write still returns commit on success. This prevents audit infrastructure issues from causing data loss.

MCP Tool Security#

MCP (Model Context Protocol) tools expose app functionality to AI agents. They must follow the same security model as UI routes — there is no separate trust boundary.

Same Auth as UI Routes#

Every MCP handler must verify platform context before doing any work:

// In your MCP route handler
const context = await getPlatformContext()
 
if (!context.trusted) {
  return Response.json({
    error: `Untrusted context: ${context.trustMode}`,
  }, { status: 403 })
}

MCP tools do not get a free pass on auth. An agent calling your tool has the same permissions as the user it acts on behalf of.

Input Validation with Strict Schemas#

Every MCP tool must declare an input schema and validate against it before processing:

• Define the expected parameters in your tool's definitions.ts.
• Validate types, required fields, enums, and string lengths in your handler.
• Reject requests that do not match the schema — do not coerce or fill in defaults silently.

Response Masking for Sensitive Fields#

MCP tool responses flow back to AI agents, which may surface them in chat, logs, or downstream tools. Mask sensitive fields before returning:

• PII (email, phone, SSN) — mask or redact based on tenant policy.
• Secrets, tokens, API keys — never include in responses.
• Internal IDs that have no user-facing meaning — omit unless needed for a follow-up action.

Use the CyberPod SDK masking service (sdk.masking) when available, or implement field-level masking in your app's service layer.

Human-in-the-Loop for Mutations#

MCP tools that write to the EDM must follow the governed write pattern:

1. Prepare the draft and return it to the agent.
2. Require explicit user confirmation before committing.
3. Never auto-commit a mutation from an MCP tool without human approval.

// Step 1: Prepare only
const prepared = await applyEdmUpdate(
  { domain: 'customer.accounts', recordId: '...', draft: {...}, commit: false, reason: 'Agent requested status change' },
  context,
)
 
// Step 2: Return diff to agent for user review
// Step 3: On explicit user confirmation, call again with commit: true

Never Expose Raw Access#

MCP tools must never:

• Expose raw SDK method calls (the agent should not call client.customer.accounts.list() directly).
• Pass through raw SQL or query builders.
• Allow unrestricted filesystem or storage browsing.
• Return app-private SQLite data, logs, cache, or temp files.
• Surface unmasked sensitive data from any source.

Wrap every capability in a purpose-built tool with a defined schema, permission check, and masked output.

Security Checklist#

Use this checklist before shipping any cPod App to production:

Context and Identity#

• Platform context is verified via getPlatformContext() before any data access or EDM read.
• Untrusted contexts (context.trusted === false) produce a clear error with the trustMode reason.
• CPOD_CONTEXT_AUDIENCE or CPOD_APP_ID is configured in every non-dev environment.
• CPOD_CONTEXT_SIGNING_SECRET is set and matches the platform's signing secret.

Governed Writes#

• All EDM mutations go through applyEdmUpdate() — no direct SDK write calls from components or handlers.
• Write gates pass (validation.warnings is empty) before any write is committed.
• The reason field on every write is specific and human-readable (not a generic string like "update").
• High-risk writes use commit: false first and require explicit user confirmation.

Audit and Observability#

• Audit events are emitted for all writes (automatic via applyEdmUpdate).
• CPOD_API_KEY is configured in every non-dev environment so audit and write paths function.

MCP Tools#

• Every MCP tool handler verifies platform context before processing.
• Input is validated against a declared schema.
• Sensitive fields are masked in responses.
• Mutation tools use prepare-then-commit with human confirmation.
• No tool exposes raw SDK calls, raw storage, SQLite, or filesystem access.

Architecture#

• React components and UI code call lib/services.ts — never raw SDK, storage, or SQLite directly.
• The app's lib/edm.ts declares edmDomains and permissionMap explicitly.
• Demo and emulator data is visibly labeled in the UI (source: 'demo_fixture' or source: 'cyberpod-emulator').
• Demo records are never submitted into live write paths.