Skip to content

SECURITY.md

Latest commit

 

History

History
157 lines (109 loc) · 6.57 KB

SECURITY.md

File metadata and controls

157 lines (109 loc) · 6.57 KB
Raw

Security Policy

Supported line

The actively maintained SDK package line is 2.x. Deployed contracts are versioned independently; support for a contract version depends on the identifiers currently documented in sdk/contracts.js and docs/CONTRACTS.md.

Reporting a vulnerability

Do not publish an unresolved vulnerability, private key, exploit transaction, or reproducible attack path in a public issue.

Preferred reporting flow:

  1. use GitHub private vulnerability reporting from the repository Security tab when that option is available;
  2. otherwise contact the repository maintainer through the linked GitHub profile before sending sensitive reproduction details;
  3. include the affected component, network, contract identifier or package version, reproducible steps, observed behavior, expected behavior, and potential impact;
  4. remove seed phrases, private keys, access tokens, personal data, and unrelated wallet information from the report.

A useful report should state whether the issue affects:

  • a deployed Clarity contract;
  • the canonical contract registry;
  • the SDK package;
  • the reference frontend;
  • wallet transaction construction;
  • optional Supabase behavior;
  • build, CI, or release infrastructure.

Security model

Authoritative state

Confirmed Clarity contract state is authoritative. Frontend state and Supabase data are convenience layers and must not override chain truth.

Authorization

Clarity contracts must enforce ownership, admin roles, minting rights, mission completion, badge claims, and asset movement. Frontend eligibility checks are user-experience controls, not authorization controls.

Transaction finality

A wallet callback means a transaction was submitted. The application must keep the operation pending until the transaction status and expected on-chain state are confirmed.

Contract identifiers

Production identifiers are centralized in sdk/contracts.js. Duplicating contract addresses in UI code creates configuration drift and can route users to an unintended contract.

Network selection

Choosing 'testnet' or 'mainnet' changes the network object. It does not automatically select a matching deployer and contract registry. Custom deployments must provide explicit identifiers.

Sensitive data rules

Never commit or expose:

  • seed phrases;
  • deployer private keys;
  • wallet private keys;
  • npm authentication tokens;
  • GitHub tokens;
  • Supabase service-role keys;
  • privileged API credentials;
  • production multisig signer material.

Only browser-safe anonymous Supabase configuration belongs in Vite environment variables. Any variable bundled into frontend code must be treated as public.

Asset-moving transactions

Use restrictive post conditions for calls that can transfer, mint, burn, or lock assets. PostConditionMode.Deny is the preferred default when all expected asset movements are declared.

Review:

  • asset type and contract identifier;
  • sender and recipient;
  • maximum amount;
  • mint and burn behavior;
  • failure behavior when post conditions do not match;
  • whether a permissive mode could hide unexpected movement.

Do not weaken post conditions merely to make a wallet request pass.

Mission reward trust boundary

The v10 mission compatibility interface accepts a caller-supplied reward argument. The reference application derives rewards from MISSION_CATALOG, but frontend-controlled input is not a security boundary.

Current safeguards and requirements:

  • callers must not enter arbitrary reward values;
  • frontend integrations must derive values from the canonical catalog;
  • contracts must enforce authorized execution and duplicate-completion rules;
  • tests must cover manipulated arguments and unauthorized callers;
  • a future contract version should resolve rewards from contract-controlled state.

Dependency and supply-chain controls

  • Install with committed lockfiles using npm ci.
  • Review changes to lockfiles and package publication contents.
  • Run public SDK tests and the production build before release.
  • Run Clarinet/Simnet tests for included contracts.
  • Publish the npm package only from a clean, reviewed commit.
  • Do not execute unreviewed deployment scripts with funded keys.
  • Treat registry changes as production behavior changes.

Administrative operations

Administrative and upgrade-sensitive actions should use a documented multisig process before production scale. The process should identify:

  • required signers and threshold;
  • signer rotation and recovery;
  • approved operation types;
  • transaction review procedure;
  • deployment record retention;
  • incident response and emergency communication.

A single locally stored production key is not the target operating model.

Current limitations

  • No independent third-party audit has been completed.
  • Administrative operations do not yet have a fully documented multisig process.
  • No protocol-wide pause mechanism is available.
  • Deployed contract logic requires a new version for behavioral changes.
  • The v10 mission interface retains caller-supplied reward arguments for compatibility.
  • The local Clarinet workspace does not contain every contract configured by the mainnet registry.
  • The SDK does not currently provide high-level transaction-write helpers.
  • Transaction confirmation and activity-history UX can be expanded.

These limitations must be disclosed to integrators and considered before production use involving meaningful asset value.

Required review for sensitive changes

Changes to any of the following require tests, documentation, and explicit security review:

  • authorization or admin principals;
  • mission rewards;
  • minting, burning, transfers, or token metadata;
  • badge ownership and claim logic;
  • contract identifiers;
  • network defaults;
  • post conditions;
  • wallet scopes;
  • decoded return shapes used for authorization decisions;
  • package exports;
  • deployment and release scripts;
  • Supabase policies or privileged credentials.

Incident response

When a credible issue is found:

  1. preserve the report and affected identifiers;
  2. stop unsafe frontend or release paths when possible;
  3. determine whether the issue is frontend, SDK, registry, infrastructure, or immutable contract logic;
  4. avoid claiming recovery before confirmed chain state is verified;
  5. prepare a versioned contract migration when deployed logic is affected;
  6. publish a corrected SDK or frontend release when applicable;
  7. document impact, affected versions, remediation, and remaining risk after sensitive details can be disclosed safely.

See Contract Inventory, Write Transactions, and Deployment Guide.