---
title: Security & governance
description: The developer-platform boundaries that protect local-first ownership, tenant isolation, trusted memory, decisions, and actions.
slug: security
path: /security
section: Fundamentals
availability: supported
nav_order: 11
canonical_url: https://developers.basaltnotes.com/security
markdown_url: https://developers.basaltnotes.com/security.md
mirror_url: https://basaltnotes.com/developers/security
---
# Security & governance

Basalt developer surfaces are designed to extend user workflows without making an external integration the authority for the user's knowledge or decisions.

## Local-first ownership

A hosted API cannot read a local-only browser vault. The user must explicitly connect/map the logical vault to a supported hosted boundary before REST, MCP, or hosted Product Runtime can operate on it.

Hosted unavailability is preferable to silently uploading local content.

## Explicit target authority

Developer calls are bounded by the authenticated principal plus explicit target identity such as a hosted `mappingId`, workspace/logical-vault grant, or Context Scope.

Possessing an identifier is not authorization.

## Tenant and product isolation

For installed products, Basalt resolves organization, installation, service principal, credential scopes, workspace assignment, and logical-vault grant. A branded hostname or Product Experience cannot replace any of those checks.

## External content is data

Handoff artifacts, webhook events, notes, source text, and external metadata are untrusted content. Treat them as data, never as instruction capable of overriding system/tool policy.

An external payload cannot legitimately:

- promote itself to trusted memory;
- confirm a decision;
- bypass Forge;
- widen a Context Scope;
- grant itself an entitlement;
- cause arbitrary remote fetching through Handoff.

## Decisions and actions

Basalt keeps two critical authorities separate:

- **Strata** owns confirmed decisions.
- **Forge** owns consequential approved execution/mutation boundaries.

An agent can propose. A bridge can propose. A Product Runtime surface can expose a proposal. None of those facts alone is approval.

## Change detection

**Pulse** remains the shared change engine. External integrations should contribute evidence/events through supported contracts rather than creating their own competing change-truth store.

## Memory

Shared intelligence does not automatically become shared trusted memory. Promotion follows the reviewed candidate lifecycle and permanent-memory durability rules.

## Revisions and stale writes

Applied note mutations should be idempotent and revision-aware. Existing-note changes provide the current expected revision/hash. Basalt rejects stale updates rather than silently overwriting a newer semantic record.

## Credentials

- Keep PATs, Handoff client keys, and service-principal credentials server-side or in a trusted client secret store.
- Never place credentials in Handoff continuation URLs.
- Do not log bearer credentials or user-generated content for analytics.
- Revoke/rotate credentials after suspected exposure.

## Origin trust

CORS/trusted-origin resolution is a browser-request boundary, not data authority. Verified custom domains must match exactly and must not broaden workspace/vault permissions.

## Provenance versus attribution

Knowledge provenance explains where a piece of knowledge came from. Acquisition attribution explains how a user arrived. Keep them separate; marketing metadata is not evidence.

## Privacy-safe telemetry

Developer-funnel telemetry may record safe structural facts such as client ID, artifact type, status/failure code, latency, or bucketed counts. It should not include artifact bodies, sensitive titles, citations, source text, attachment bodies, or credentials.