Self Lock – Chrome Extension

Self Lock is a Chrome extension that locks selected websites behind a Self Protocol verification flow.

Before visiting certain sites (social media, NSFW, personal email, etc.), you must prove “you’re you” using the Self app. Once verified, all protected sites are unlocked for a time‑limited session. When the timer expires, those sites blur/lock again automatically, even if the tab is still open.

Highlights

• Self‑gated browsing – Require a Self verification before visiting chosen sites.
• Time‑boxed sessions – Unlock all protected sites for N minutes, then auto‑relock.
• Overlay blur – Protected pages are blurred with a clean “Self Lock enabled” notice.
• Quick site control – One‑click toggle to protect/unprotect the current domain.
• Privacy‑first – Uses Self proofs; extension only sees verification status and basic summary.

Project Structure

• chrome-extension/ – the actual Self Lock Chrome extension
  • src/background.ts – Manifest V3 service worker managing session + site lock state.
  • src/contentScript.ts – Injected into pages; adds/removes the blur overlay.
  • src/popup/ – React + Tailwind popup UI (shadcn-style layout).
  • public/self-icon.png – Extension icon.
  • vite.config.ts / tsconfig.json / tailwind.config.mjs – build & tooling.
• server/ – optional Express backend that verifies Self proofs
  • Uses SelfBackendVerifier from @selfxyz/core.
  • Configured for staging/mock passports with OFAC enabled.
• banner.png, README.md, .gitignore, prettier.config.cjs – repo metadata and tooling.

The client demo app has been removed to keep this repo focused on the extension.

Prerequisites

• Node.js 18+ (Self SDK recommends Node 22; you may see engine warnings on other versions).
• npm (comes with Node).
• Google Chrome or Chromium-based browser with Manifest V3 support.
• A working Self backend (you can use the provided server/ folder or your own).

1. Backend Setup (Self Verifier)

Self Lock expects a Self verification endpoint that:

• Accepts a proof from the Self app.
• Validates it using SelfBackendVerifier.
• Exposes a small debug endpoint returning the last verification result.

This repo includes a minimal Express backend at server/ that does exactly that.

1.1 Install backend dependencies

cd server
npm install

1.2 Configure backend environment

Create server/.env:

PORT=3001
SELF_SCOPE=demo-scope
SELF_ENDPOINT=https://your-ngrok-id.ngrok-free.app/api/verify

• PORT – local port for Express.
• SELF_SCOPE – Self scope; must match the extension’s scope.
• SELF_ENDPOINT – public URL for /api/verify (e.g. an ngrok URL pointing to this backend).

1.3 Run the backend

cd server
npm run dev

The backend exposes:

• POST /api/verify – main Self verification endpoint.
• GET /debug/last-result – returns the last verification result (used by the extension to build a friendly summary).

1.4 Expose the backend (optional but recommended)

To use the extension from a real device with the Self app:

ngrok http 3001

Take the URL (e.g. https://xxxx.ngrok-free.app/api/verify) and plug it into:

• SELF_ENDPOINT in server/.env.
• VITE_SELF_ENDPOINT in chrome-extension/.env.

2. Extension Setup

The extension lives entirely in chrome-extension/.

2.1 Install extension dependencies

cd chrome-extension
npm install

2.2 Configure extension environment

Create chrome-extension/.env (this file is ignored by git; the values below are examples):

VITE_SELF_APP_NAME=Self Lock
VITE_SELF_SCOPE=demo-scope
VITE_SELF_ENDPOINT=https://your-ngrok-id.ngrok-free.app/api/verify
VITE_SELF_DEBUG_ENDPOINT=http://localhost:3001/debug/last-result
VITE_SESSION_MINUTES=20

• VITE_SELF_APP_NAME – name shown in Self app.
• VITE_SELF_SCOPE – must match SELF_SCOPE from server/.env.
• VITE_SELF_ENDPOINT – must match SELF_ENDPOINT from server/.env.
• VITE_SELF_DEBUG_ENDPOINT – points to the backend’s debug endpoint.
• VITE_SESSION_MINUTES – default length for a Self session (in minutes).

2.3 Build the extension bundle

cd chrome-extension
npm run build

This produces a dist/ directory with:

• manifest.json – extension manifest (MV3).
• background.js – built background service worker.
• contentScript.js – built content script.
• popup.js + index.html – popup UI bundle.
• assets/* – CSS and shared chunks.
• self-icon.png – extension icon.

chrome-extension/dist/ is intentionally not committed; regenerate it via npm run build when needed.

2.4 Load in Chrome

1. Open chrome://extensions in Chrome.
2. Enable Developer mode (toggle in the top-right).
3. Click Load unpacked.
4. Select the chrome-extension/dist folder.

You should now see Self Lock in your extension list with the Self icon.

3. How Self Lock Works

At a high level:

• The popup lets you:
  • Mark the current domain as “protected”.
  • See whether your session is Locked or Unlocked.
  • Trigger a Self verification by scanning a QR code.
  • Adjust the session length and end the session early.
• The background service worker:
  • Tracks:
    • protectedSites – list of hostnames to guard.
    • session – { verified, expiresAt, verificationSummary }.
  • Observes tab updates:
    • Whenever a tab finishes loading, decides whether that host should be locked or unlocked.
  • Notifies the content script to lock/unlock pages.
• The content script:
  • Blurs protected pages with a high‑z overlay stating “Self Lock enabled”.
  • Listens for lock/unlock/session update messages.
  • Locally tracks when the session expires (based on expiresAt) and re‑applies the overlay without requiring a refresh.

All long‑lived state lives in chrome.storage.local so it persists across browser restarts.

4. Using the Extension

1. Start your backend

   Ensure the backend in server/ is running and reachable from the extension (ngrok if needed).

2. Protect a site

   • Navigate to a site you want to gate (e.g. https://twitter.com).
   • Click the Self Lock extension icon to open the popup.
   • Inside the Current site card, click the pill so it reads “Protected with Self”.
   • The page will blur and show the Self Lock overlay.

3. Verify with Self

   • In the popup, scroll to the combined Session section and find the Verify with Self area.
   • Open the Self app on your phone (staging/mock passports).
   • Scan the QR code.
   • On success, the extension calls the backend’s debug endpoint to summarize your verification and creates a session for VITE_SESSION_MINUTES.
   • The overlay disappears and all protected sites are unlocked for the duration of the session.

4. Automatic relock

   • When the timer expires, the content script detects it and re‑applies the blur overlay on any open protected pages, without requiring a refresh.

5. Manually end session

   • From the popup’s Session card, click End session.
   • All protected sites immediately blur again until you re‑verify with Self.

6. Manage multiple sites

   • Use the Protected sites card at the bottom of the popup to add/remove domains.
   • All protected domains share the same Self session (one verification unlocks them all).

5. Development Notes

• The popup UI is built with React + Tailwind and styled in a shadcn-like dark theme.
• Chrome integration uses:
  • Manifest V3 background service worker (background.ts).
  • chrome.storage.local for session + config.
  • chrome.tabs, chrome.runtime.onMessage for messaging between popup, background, and content script.
• Self integration uses:
  • @selfxyz/qrcode for the QR rendering.
  • @selfxyz/core for building the universal link and backend verification.

If you tweak backend URLs or scopes, make sure server/.env and chrome-extension/.env stay in sync.

6. Packaging

When you’re ready to share the extension:

1. Run a fresh build:

   cd chrome-extension
   npm run build

2. Zip the dist/ folder (contents must include manifest.json at the root of the zip).

3. Upload that zip to the Chrome Web Store or distribute it manually.