Browser Extension

Browser extensions provide a secure environment for identity management with protection against web-based attacks through script isolation.

Security Model

Feature	Description
Isolated Context	Background script runs in isolated environment
XSS Protection	Website compromises cannot access extension storage
Browser Encryption	Chrome Storage API provides encrypted persistence
CSP Enforcement	Content Security Policy prevents injection attacks
Same-Origin Bypass	Extension context bypasses same-origin restrictions

Architecture Overview

Installation

Manifest Configuration

Manifest V3 (Chrome)

Firefox (Manifest V2/V3)

Background Script Setup

The background script is the core of your extension, running the SDK in an isolated context.

Content Script for HSM Bridge

The content script handles HSM UI operations that require user interaction.

Web Page Communication

Communicate with web pages to handle credential offers:

Offscreen Document (Persistent Background)

For operations requiring persistent background processing in Manifest V3:

Build Configuration

Webpack

Vite

Testing

Load Unpacked Extension

Build your extension: npm run build
Open Chrome and navigate to chrome://extensions
Enable "Developer mode"
Click "Load unpacked" and select your dist folder

Debug Background Script

On chrome://extensions, find your extension
Click "service worker" link to open DevTools
Set breakpoints and inspect state

Troubleshooting

Service Worker Stops

Manifest V3 service workers can be terminated. Persist state in Chrome Storage:

CORS Issues

Use the background script for all API calls to bypass CORS:

Next Steps

Authentication Guide
Zero-Knowledge Proofs
API Reference

Security Model

Feature	Description
Isolated Context	Background script runs in isolated environment
XSS Protection	Website compromises cannot access extension storage
Browser Encryption	Chrome Storage API provides encrypted persistence
CSP Enforcement	Content Security Policy prevents injection attacks
Same-Origin Bypass	Extension context bypasses same-origin restrictions

Architecture Overview

Testing

Load Unpacked Extension

Build your extension: npm run build

Open Chrome and navigate to chrome://extensions

Enable "Developer mode"

Click "Load unpacked" and select your dist folder

Debug Background Script

On chrome://extensions, find your extension

Click "service worker" link to open DevTools

Set breakpoints and inspect state

import { DCIDClient } from '@dcid/sdk'; class BackgroundService { private client: DCIDClient; async initialize() { this.client = new DCIDClient({ platform: 'extension', config: { appId: 'your-signing-app-id', appIdEncryption: 'your-encryption-app-id', env: 'prod' }, apiUrl: 'https://api.your-backend.com' }); await this.client.initialize(); this.setupMessageListeners(); } private setupMessageListeners() { chrome.runtime.onMessage.addListener((request, sender, sendResponse) => { this.handleMessage(request, sender).then(sendResponse); return true; // Keep channel open for async response }); } private async handleMessage(request: any, sender: chrome.runtime.MessageSender) { switch (request.type) { case 'GET_AUTH_STATE': return { isAuthenticated: this.client.auth.isAuthenticated(), email: this.client.auth.getUserEmail() }; case 'INITIATE_SIGN_IN': await this.client.auth.initiateSignIn(request.email); return { success: true }; case 'CONFIRM_OTP': const tokens = await this.client.auth.confirmCode( request.email, request.code ); await this.client.auth.login(tokens.accessToken, tokens.refreshToken); return { success: true }; case 'SIGN_OUT': await this.client.auth.logout(); return { success: true }; case 'HANDLE_CREDENTIAL_OFFER': const email = this.client.auth.getUserEmail(); const token = await this.client.auth.getAccessToken(); const result = await this.client.credentials.handleCredentialOffer({ emailOrPhone: email, credentialUrl: request.url, accessToken: token }); return { success: result }; case 'GENERATE_PROOF': const userEmail = this.client.auth.getUserEmail(); const accessToken = await this.client.auth.getAccessToken(); const proof = await this.client.proofs.createAndVerifyProof({ emailOrPhone: userEmail, proofRequestUrl: request.url, accessToken: accessToken }); return { success: true, proof }; default: return { error: 'Unknown message type' }; } } } // Initialize on extension load const service = new BackgroundService(); service.initialize();

Browser Extension

Security Model

Architecture Overview

Installation

Manifest Configuration

Manifest V3 (Chrome)

Firefox (Manifest V2/V3)

Background Script Setup

Content Script for HSM Bridge

Popup UI

Web Page Communication

Offscreen Document (Persistent Background)

Build Configuration

Webpack

Vite

Testing

Load Unpacked Extension

Debug Background Script

Troubleshooting

Service Worker Stops

CORS Issues

Next Steps

SDK Reference

Browser Extension

Security Model

Architecture Overview

Installation

Manifest Configuration

Manifest V3 (Chrome)

Firefox (Manifest V2/V3)

Background Script Setup

Content Script for HSM Bridge

Popup UI

Web Page Communication

Offscreen Document (Persistent Background)

Build Configuration

Webpack

Vite

Testing

Load Unpacked Extension

Debug Background Script

Troubleshooting

Service Worker Stops

CORS Issues

Next Steps

SDK Reference