Security guide

This guide explains how applications should use @beblurt/dblurt safely.

For the strategic model and classification of known risks, see ../architecture/SECURITY_ARCHITECTURE.md.

Responsibility split

@beblurt/dblurt is an SDK. It constructs RPC calls, serializes operations, signs transactions locally and exposes Blurt Layer 1 / Nexus Layer 2 helpers.

Applications remain responsible for:

• deciding what a user is allowed to sign;
• storing and protecting private keys;
• choosing trusted RPC endpoints;
• validating business rules;
• protecting browser applications from XSS and supply-chain attacks;
• distinguishing Layer 1 truth from Nexus indexed views.

Private keys

Never hard-code private keys in source code, examples or tests.

Use environment variables, encrypted stores, wallet integrations or user-controlled signing flows:

const { PrivateKey } = require('@beblurt/dblurt');

const rawKey = process.env.BLURT_POSTING_KEY;
if (!rawKey) {
    throw new Error('Set BLURT_POSTING_KEY before signing');
}

const key = PrivateKey.fromString(rawKey);
Copy

Owner keys should not be used in normal application flows. Prefer the least powerful authority required by the operation.

Authorities

Common authority guidance:

Authority	Typical use
Posting	social actions such as votes/comments where supported
Active	value-moving or account-management actions such as transfers
Owner	recovery / highest-risk account authority; avoid in applications
Memo	memo encryption/decryption only; not transaction authority

Before broadcasting, verify the operation's required authority against source, tests, TypeDoc or protocol documentation.

@beblurt/dblurt exposes local authority-validation primitives for least-privilege checks:

• evaluateAuthorityForKey(authority, key) evaluates a single Layer 1 authority object against one public/private key;
• validatePostingAuthority(account, key, { getAccount }) checks an already-loaded account object, including delegated posting authorities;
• client.condenser.validatePostingAuthority(accountName, key) reads Layer 1 account authority state via condenser_api.get_accounts and follows delegated posting accounts before returning an explanatory result.

These helpers do not broadcast, sign, store keys, or replace application policy. They answer whether the key satisfies the requested authority and expose owner/active matches so applications can warn when a high-privilege key is being used for a posting-only workflow.

RPC endpoints

RPC endpoints are not automatically trusted just because they speak Blurt JSON-RPC.

Use trusted HTTPS endpoints for production. Server-side applications should not accept arbitrary user-provided RPC URLs without allowlisting and network egress controls.

Risk examples:

• A malicious RPC can return misleading read data.
• A malicious RPC can influence transaction preparation data such as head block number, head block id and time.
• User-controlled RPC URLs in backend services can become SSRF.

For endpoint lists and failover behavior, see failover.md.

Layer 1 and Nexus

Layer 1 RPC is the canonical blockchain source.

Nexus Layer 2 is an indexed/social/query layer built from Layer 1 data. It is useful for community and discovery workflows, but it should not be treated as replacing Layer 1 consensus truth.

Security-sensitive decisions should validate the relevant Layer 1 state when appropriate.

Broadcasting

Broadcasting has irreversible side effects once accepted by the blockchain.

Before calling client.broadcast:

1. Build the operation from explicit user intent.
2. Confirm the required authority.
3. Confirm the amount, account names, permlink and memo.
4. Use a trusted RPC endpoint list.
5. Keep the local transaction id for ambiguous network failures.

Read broadcast.md before implementing signing flows.

Assets and amounts

Blockchain asset amounts must be exact.

Until exact integer asset parsing/serialization is fully hardened, applications should avoid constructing large or user-supplied asset amounts without their own validation. Treat unusually large values, exponential notation and values near JavaScript safe-integer limits as unsafe.

Encrypted memos

Encrypted memos use legacy Blurt/Graphene-compatible memo semantics.

Important security property:

• encrypted memos are intended for confidentiality;
• the legacy format should not be described as modern authenticated encryption;
• memo keys are not transaction signing authorities.

Do not log sensitive decrypted memo plaintext.

See crypto.md for API usage and ../architecture/SECURITY_ARCHITECTURE.md for the architectural classification.

Browser applications

Browser signing is high risk because any XSS, malicious extension or compromised dependency can access key material handled by the page.

Prefer:

• read-only browser flows;
• wallet or user-approval integrations;
• self-hosted bundles or pinned CDN versions;
• Subresource Integrity when using CDN scripts;
• strict Content Security Policy where practical.

See browser.md.

Package usage

For production package consumption:

• pin versions deliberately;
• review package updates before deployment;
• run tests against your real signing and broadcast flows;
• avoid relying on @latest for CDN or npm installs;
• run a clean consumer smoke test before release.

Reporting security issues

See ../SECURITY.md for vulnerability reporting guidance.