@bsv/sdk 1.9.3 → 1.9.4

package/docs/concepts/identity-certificates.md

@@ -1,307 +0,0 @@
-# Identity Certificates
-
-Understanding how cryptographic certificates work to establish trust and verify identity claims in decentralized systems.
-
-## What are Identity Certificates?
-
-Think of identity certificates as digital testimonials that can't be forged. Just like a diploma proves you graduated from a university, or a driver's license proves you're authorized to drive, identity certificates prove specific claims about who you are or what you're authorized to do.
-
-The key difference is that these digital certificates use cryptographic signatures instead of physical security features, making them verifiable by anyone with the right tools, anywhere in the world.
-
-## How Certificates Create Trust
-
-### The Trust Problem
-
-In the digital world, it's easy to claim anything about yourself. Anyone can create a website saying they're a doctor, lawyer, or certified professional. How do you know who to trust?
-
-### The Certificate Solution
-
-Certificates solve this by having trusted third parties vouch for specific claims. When a university issues you a digital diploma certificate, they're cryptographically signing a statement that says "We verify that this person graduated from our program."
-
-Anyone can then verify:
-
-1. **The certificate is authentic** (cryptographic signature is valid)
-2. **It hasn't been tampered with** (any changes would break the signature)
-3. **It's still valid** (hasn't expired or been revoked)
-4. **The issuer is trustworthy** (you trust the university)
-
-## Types of Certificates
-
-### Self-Signed Certificates
-
-These are claims you make about yourself, like "My name is John Doe" or "My email is <john@example.com>." While anyone can create these, they serve as a starting point for building your digital identity.
-
-**When they're useful:**
-
-- Basic profile information
-- Contact preferences
-- Personal statements
-- Starting point for identity building
-
-**Limitations:**
-
-- Low trust value (anyone can claim anything)
-- Not suitable for high-stakes verification
-- Mainly useful for discovery and basic interaction
-
-### Peer-Verified Certificates
-
-These are endorsements from other users who can vouch for specific claims about you. Like professional references or character witnesses, they carry more weight when they come from trusted sources.
-
-**Examples:**
-
-- Colleague endorsing your professional skills
-- Friend confirming your identity
-- Community member vouching for your reputation
-- Business partner confirming successful transactions
-
-### Institutional Certificates
-
-These come from recognized organizations with established authority and verification processes. They carry the most weight because the issuers have reputations to protect and rigorous verification procedures.
-
-**Examples:**
-
-- University degree certificates
-- Professional licensing board certifications
-- Government-issued identity documents
-- Industry association memberships
-- Employer verification of work history
-
-## Certificate Lifecycle
-
-### Creation and Issuance
-
-When someone wants to issue you a certificate, they typically:
-
-1. **Verify your claim** through their established process
-2. **Create a digital certificate** containing the verified information
-3. **Sign it cryptographically** using their private key
-4. **Deliver it to you** for use in proving the claim
-
-### Validation and Trust
-
-When someone wants to verify your certificate, they:
-
-1. **Check the cryptographic signature** to ensure authenticity
-2. **Verify it hasn't expired** or been revoked
-3. **Assess the issuer's credibility** and authority
-4. **Determine if it meets their requirements** for the specific use case
-
-### Renewal and Maintenance
-
-Certificates have limited lifespans for security reasons:
-
-- **Expiration dates** ensure information stays current
-- **Renewal processes** allow for re-verification
-- **Revocation mechanisms** handle compromised or invalid certificates
-- **Update procedures** accommodate changing information
-
-## Trust Scoring and Reputation
-
-### Building Credibility
-
-Your overall trustworthiness comes from the combination of all your certificates:
-
-- **Quantity**: More verifications generally increase trust
-- **Quality**: Certificates from respected issuers carry more weight
-- **Diversity**: Different types of verification provide broader confidence
-- **Recency**: Fresh certificates are more valuable than old ones
-
-### Confidence Levels
-
-Different certificates provide different levels of assurance:
-
-- **Self-asserted claims** provide basic information but low confidence
-- **Peer verifications** offer moderate confidence from social proof
-- **Service verifications** provide higher confidence from specialized validators
-- **Institutional certificates** offer the highest confidence from established authorities
-
-### Context Matters
-
-The same certificate might be highly valuable in one context but irrelevant in another:
-
-- A medical license is crucial for healthcare but irrelevant for software development
-- A GitHub contribution history matters for programming jobs but not for teaching
-- Age verification is essential for restricted services but unnecessary for professional networking
-
-## Privacy and Selective Disclosure
-
-### Controlling Information Flow
-
-One of the key advantages of certificate-based identity is granular control over what you reveal:
-
-- **Public certificates** are discoverable by anyone
-- **Private certificates** are shared only with specific parties
-- **Selective revelation** lets you prove specific claims without revealing everything
-- **Progressive disclosure** allows trust to build gradually
-
-### Zero-Knowledge Proofs
-
-Advanced techniques allow you to prove things without revealing the underlying data:
-
-- Prove you're over 21 without revealing your exact age
-- Prove you have a degree without revealing which university
-- Prove you're a resident without revealing your exact address
-- Prove you're qualified without revealing all your credentials
-
-### Consent and Control
-
-You maintain control over your certificates:
-
-- **Choose what to make public** vs. keep private
-- **Decide who can access** specific information
-- **Revoke access** when relationships change
-- **Update preferences** as your needs evolve
-
-## Real-World Applications
-
-### Professional Verification
-
-Instead of relying on self-reported resumes, employers can verify:
-
-- Educational credentials directly from institutions
-- Work history from previous employers
-- Professional certifications from licensing bodies
-- Skills endorsements from colleagues and clients
-
-### Age and Identity Verification
-
-Services requiring age or identity verification can:
-
-- Verify age without collecting birthdates
-- Confirm identity without storing personal documents
-- Meet regulatory requirements while preserving privacy
-- Reduce fraud through cryptographic verification
-
-### Reputation Systems
-
-Platforms can build more reliable reputation systems:
-
-- Portable reputation that follows users between platforms
-- Verifiable transaction history and feedback
-- Reduced fake accounts and manipulation
-- Incentives for honest behavior
-
-### Access Control
-
-Organizations can manage access more securely:
-
-- Verify membership or employment status
-- Confirm professional qualifications
-- Validate security clearances
-- Authenticate without passwords
-
-## Benefits Over Traditional Systems
-
-### Security
-
-- **Cryptographic verification** is more secure than physical documents
-- **Tamper evidence** makes forgery virtually impossible
-- **Distributed validation** eliminates single points of failure
-- **Revocation mechanisms** handle compromised credentials quickly
-
-### Privacy
-
-- **Minimal disclosure** reveals only necessary information
-- **User control** over what information is shared
-- **No central databases** to be breached or misused
-- **Consent-based sharing** puts users in control
-
-### Interoperability
-
-- **Standard formats** work across different systems
-- **Portable credentials** move between applications
-- **Universal verification** works anywhere in the world
-- **Cross-platform compatibility** reduces vendor lock-in
-
-### Efficiency
-
-- **Automated verification** reduces manual processes
-- **Real-time validation** provides instant results
-- **Reduced paperwork** streamlines credential management
-- **Lower costs** compared to traditional verification methods
-
-## Challenges and Considerations
-
-### User Experience
-
-Making certificate systems user-friendly requires:
-
-- **Intuitive interfaces** that hide complexity
-- **Clear explanations** of what certificates mean
-- **Simple management tools** for organizing credentials
-- **Seamless integration** with existing workflows
-
-### Recovery and Backup
-
-Unlike traditional documents, losing access to digital certificates can be permanent:
-
-- **Backup strategies** are essential for important credentials
-- **Recovery mechanisms** must balance security with usability
-- **Key management** becomes critical for certificate access
-- **Succession planning** for organizational certificates
-
-### Adoption and Network Effects
-
-Certificate systems become more valuable as adoption grows:
-
-- **Issuer participation** is needed for valuable certificates
-- **Verifier acceptance** determines practical utility
-- **User adoption** creates network effects
-- **Standardization** enables interoperability
-
-### Legal and Regulatory
-
-Integrating with existing legal frameworks requires:
-
-- **Regulatory compliance** with identity verification laws
-- **Legal recognition** of digital certificates
-- **Audit trails** for compliance reporting
-- **Dispute resolution** mechanisms for conflicts
-
-## The Future of Digital Credentials
-
-As certificate-based identity systems mature, we can expect:
-
-### Widespread Adoption
-
-- **Government integration** with official identity documents
-- **Educational institutions** issuing digital diplomas
-- **Professional organizations** moving to digital certifications
-- **Employers** accepting and requiring digital credentials
-
-### Enhanced Privacy
-
-- **Zero-knowledge proofs** becoming standard
-- **Selective disclosure** built into all systems
-- **Privacy-preserving verification** as the default
-- **User control** over all personal data
-
-### Improved User Experience
-
-- **Seamless integration** with daily digital activities
-- **Automated verification** reducing friction
-- **Intelligent recommendations** for credential building
-- **Universal acceptance** across platforms and services
-
-### New Possibilities
-
-- **Micro-credentials** for specific skills and achievements
-- **Dynamic certificates** that update automatically
-- **Composite credentials** combining multiple sources
-- **AI-assisted verification** for complex claims
-
-Understanding these concepts helps developers and users participate in building a more trustworthy, privacy-preserving digital world where identity verification is both secure and user-controlled.
-
-## Related Concepts
-
-- [Decentralized Identity](./decentralized-identity.md) - Overall identity system architecture
-- [Digital Signatures](./signatures.md) - Cryptographic foundations of certificates
-- [Trust Model](./trust-model.md) - Security assumptions and trust relationships
-- [Key Management](./key-management.md) - Managing cryptographic keys for certificates
-
-## Further Reading
-
-- [Identity Management Tutorial](../tutorials/identity-management.md) - Practical certificate implementation
-- [Security Best Practices](../guides/security-best-practices.md) - Secure certificate handling
-- [AuthFetch Tutorial](../tutorials/authfetch-tutorial.md) - Using certificates for authentication

package/docs/concepts/index.md

@@ -1,77 +0,0 @@
-# Concepts
-
-Essential concepts for understanding and using the BSV TypeScript SDK effectively.
-
-## Core Bitcoin Concepts
-
-### [Transaction Structure](./transaction-structure.md)
-
-Understanding Bitcoin transactions, inputs, outputs, and how they work in the SDK.
-
-### [Script Templates](./script-templates.md)
-
-Standard and custom Bitcoin script patterns available in the SDK.
-
-### [Digital Signatures](./signatures.md)
-
-How digital signatures work in Bitcoin and their implementation in the SDK.
-
-### [Transaction Verification](./verification.md)
-
-Understanding how to verify Bitcoin transactions using the SDK.
-
-### [SPV Verification](./spv-verification.md)
-
-Simplified Payment Verification and merkle proof concepts for lightweight clients.
-
-### [Transaction Fees](./fees.md)
-
-How Bitcoin transaction fees work and fee optimization strategies.
-
-## SDK Architecture
-
-### [SDK Design Philosophy](./sdk-philosophy.md)
-
-Core principles: zero dependencies, SPV-first approach, and vendor neutrality.
-
-### [Wallet Integration](./wallet-integration.md)
-
-How the SDK connects with Bitcoin wallets and manages authentication.
-
-### [Chain Tracking](./chain-tracking.md)
-
-Understanding how the SDK interacts with the Bitcoin network for transaction data.
-
-## Data Formats
-
-### [BEEF Format](./beef.md)
-
-Bitcoin Extras Extension Format for efficient transaction data exchange.
-
-### [Transaction Encoding](./transaction-encoding.md)
-
-How transactions are serialized and deserialized in the SDK.
-
-## Identity and Certificates
-
-### [Decentralized Identity](./decentralized-identity.md)
-
-Understanding BSV's decentralized identity system and certificate-based verification.
-
-### [Identity Certificates](./identity-certificates.md)
-
-How cryptographic certificates work for identity claims and verification.
-
-## Security Model
-
-### [Key Management](./key-management.md)
-
-How private keys, public keys, and cryptographic operations work in the SDK.
-
-### [Trust Model](./trust-model.md)
-
-Understanding the security assumptions and trust relationships in SDK applications.
-
----
-
-These concepts provide the foundational knowledge needed to build Bitcoin applications with the BSV TypeScript SDK. For deeper protocol details, refer to the [BSV Skills Center](https://docs.bsvblockchain.org/).

package/docs/concepts/key-management.md

@@ -1,185 +0,0 @@
-# Key Management
-
-Understanding how private keys, public keys, and cryptographic operations work in the BSV TypeScript SDK.
-
-## Cryptographic Keys
-
-Bitcoin uses elliptic curve cryptography (secp256k1) for key management:
-
-```typescript
-import { PrivateKey, PublicKey } from '@bsv/sdk'
-
-// Generate a new private key
-const privateKey = PrivateKey.fromRandom()
-
-// Derive the corresponding public key
-const publicKey = privateKey.toPublicKey()
-```
-
-## Private Keys
-
-Private keys are 256-bit numbers that control Bitcoin funds:
-
-### Generation
-
-```typescript
-// Secure random generation
-const privKey = PrivateKey.fromRandom()
-
-// From existing data (use carefully)
-const privKey2 = PrivateKey.fromString('hex_string')
-```
-
-### Formats
-
-```typescript
-// WIF (Wallet Import Format)
-const wif = privateKey.toWif()
-
-// Hex string
-const hex = privateKey.toString()
-
-// DER encoding
-const der = privateKey.toDER()
-```
-
-## Public Keys
-
-Public keys are derived from private keys and can be shared safely:
-
-### Derivation
-
-```typescript
-// Always derive from private key
-const publicKey = privateKey.toPublicKey()
-
-// Cannot go backwards (public -> private)
-```
-
-### Formats
-
-```typescript
-// Compressed (33 bytes) - preferred
-const compressed = publicKey.toString()
-
-// Uncompressed (65 bytes) - legacy
-const uncompressed = publicKey.toString(false)
-
-// DER encoding
-const der = publicKey.toDER()
-```
-
-## Digital Signatures
-
-Private keys create signatures that prove ownership:
-
-```typescript
-// Sign a message
-const message = 'Hello Bitcoin'
-const signature = privateKey.sign(message)
-
-// Verify with public key
-const isValid = publicKey.verify(message, signature)
-```
-
-## Key Derivation
-
-The SDK supports hierarchical key derivation:
-
-```typescript
-// Derive child keys (simplified example)
-const childKey = privateKey.deriveChild(0)
-const childPubKey = childKey.toPublicKey()
-```
-
-## Security Considerations
-
-### Private Key Security
-
-- **Never expose**: Private keys should never be logged or transmitted
-- **Secure storage**: Use encrypted storage for private keys
-- **Random generation**: Always use cryptographically secure randomness
-- **Access control**: Limit who can access private key operations
-
-### Best Practices
-
-```typescript
-// Good: Generate securely
-const key = PrivateKey.fromRandom()
-
-// Bad: Predictable generation
-const badKey = PrivateKey.fromString('1234567890abcdef...')
-
-// Good: Derive public key when needed
-const pubKey = key.toPublicKey()
-
-// Bad: Store private key unnecessarily
-localStorage.setItem('privateKey', key.toString())
-```
-
-## Wallet Integration
-
-In most applications, wallets handle key management:
-
-The `WalletClient` provides high-level key management through wallet integration:
-
-```typescript
-// Wallet manages keys securely
-const wallet = new WalletClient()
-
-// Application doesn't see private keys
-const action = await wallet.createAction({
-  outputs: [/* transaction outputs */]
-})
-```
-
-When using the `WalletClient`, keys are managed by the connected wallet service:
-
-The `WalletClient` approach is recommended for production applications as it provides:
-
-## Key Recovery
-
-Keys can be recovered from various formats:
-
-```typescript
-// From WIF format
-const key1 = PrivateKey.fromWif(wifString)
-
-// From hex string
-const key2 = PrivateKey.fromString(hexString)
-
-// From DER encoding
-const key3 = PrivateKey.fromDER(derBytes)
-```
-
-## Cryptographic Operations
-
-The SDK provides secure implementations of:
-
-- **ECDSA**: Digital signature algorithm
-- **ECDH**: Key exchange protocol
-- **Hash Functions**: SHA-256, RIPEMD-160
-- **AES**: Symmetric encryption
-
-## Memory Management
-
-Sensitive key data should be cleared when no longer needed:
-
-- Use secure memory practices
-- Clear variables containing key data
-- Avoid keeping keys in memory longer than necessary
-
-## Testing and Development
-
-For development and testing:
-
-- Use testnet for experiments
-- Generate new keys for each test
-- Never use mainnet keys in test code
-- Implement proper key rotation
-
-## Next Steps
-
-- Understand [Digital Signatures](./signatures.md) in detail
-- Learn about [Trust Model](./trust-model.md) considerations
-- Explore [Wallet Integration](./wallet-integration.md) patterns