# ClassGuard 1.9

A Chrome / Chromebook website blocker with a local dashboard, explicit school-learning permissions, local HTML game inspection, and optional managed administrator policies. Website filtering works locally. Live teacher screen viewing uses the included pairing server. This is an independent starter, not a GoGuardian product.

## Install or update

1. Unzip `classguard.zip`.
2. Open `chrome://extensions` in Chrome and enable **Developer mode**.
3. Click **Load unpacked** and select the `classguard` folder containing `manifest.json`.
4. Click the ClassGuard extension icon, then **Open dashboard**.
5. To update an existing installation, replace the folder contents and click **Reload** on its extension card. Reload already-open website tabs to install the HTML inspector in those documents.

Chrome 120 or newer is required. Managed Chromebooks may prohibit unpacked installations; their Chrome administrator must deploy the extension. This package is not published to the Chrome Web Store.

## Teacher screen viewing

Screen sharing is **required** to enter and remain in a monitored class. Open **Screen viewing → Open teacher view**, start a class, and approve joining students. Approval starts a 60-second deadline to establish sharing. The student must use **Share screen to enter class** and Chrome’s native picker. The server marks the student active only after the teacher viewer confirms it received the screen. Every connected screen plays simultaneously in the teacher grid; selecting or expanding one is optional. Compact and comfortable layouts and Focus classroom are available. The grid shows active versus joined counts.

Canceling the picker, stopping in Chrome, leaving, closing the page, or losing the screen connection ends participation. A student must rejoin and establish a screen stream to participate again. This requirement applies to the ClassGuard monitored class session; it does not lock the computer, prevent all website access, disable Chrome’s Stop control, or prove attendance in other school software.

## Websites allowed during a class period

When starting a class, teachers set its duration (1–120 minutes) and select **Only allow listed websites during this period**. Enter domain names, one per line, such as `ixl.com`. Teachers can edit the list and select **Apply to class** while teaching. Student devices must run the installed ClassGuard extension for this feature; the browser-only student page refuses to enter a website-restricted class.

During an IXL-only class, `ixl.com` and its subdomains are allowed subject to the district policy; other HTTP/HTTPS pages and embedded frames are blocked, including other education-list websites, .edu domains, and personal allow exceptions. District custom blocks still apply to lesson sites. Already-open off-list web tabs are redirected to the blocked page, and later tab URL changes are checked locally. The teacher can include login or supporting frame domains if a lesson needs them. Image/script/API requests are not globally blocked, so allowed pages can still load their assets.

The class restriction remains after the student stops sharing, leaves, or closes the student page. Only the teacher ending the class, disabling that class website restriction, or the scheduled period expiry releases it. The extension checks the server every 30 seconds while Chrome is running; edits and early class ending can therefore take up to one polling interval on a detached sharing page. If the server is unreachable or Chrome restarts, the last class rule stays until the previously scheduled period expiry. Class metadata is kept locally; its server session credential is kept in Chrome’s extension session storage, which clears when Chrome exits. There is no student-facing action to cancel the class restriction.

Normal local/managed school settings are preserved and used when the class restriction ends. New `tabs` permission inspects current tab URLs only to enforce the class list; it does not upload URLs or store browsing history. `alarms` keeps policy polling and expiry independent of the sharing page. Unpacked extensions can still be removed or modified; enforce installation and the relevant Chrome administrator policies for a managed school deployment.

No screen starts sharing automatically. Each screen selection uses Chrome's native picker. Audio and microphone capture are not requested. Teacher access is controlled by a separate private staff key; students receive class invitation codes and, for roster classes, personal enrollment codes. Open classes use self-reported display names. Roster classes bind names and class groups to a personal enrollment code. This is not school SSO or verified email authentication.

Update the extension and server together to version 1.9.0; older teacher viewers do not implement the required screen heartbeat. The download includes a sibling `classguard-server` folder. Follow its README to start a localhost test or deploy a school-controlled HTTPS pairing server for multiple devices. The server relays connection messages and holds temporary class metadata; video is streamed through WebRTC and not recorded. School NAT/firewall configurations may require configured STUN/TURN services. The existing filtering rules, .edu permission, and 2,252-domain learning list are unchanged.

Validation covers filtering rules, required-sharing admission, teacher-only stream confirmation, sharing deadlines, stop/removal, and screen-heartbeat expiry. Synthetic streams are used for browser QA. Real desktop capture in an installed extension and a real school network have not been tested in this workspace.

## School learning whitelist

The bundled list now contains **2,252 explicit resource domains**, enabled by default. It includes IXL, i-Ready, Freckle, ST Math, Lexia Core5, Khan Academy, ReadWorks, CommonLit, Google Classroom, reading/math/science/coding tools, classroom resources, and supporting login/content hosts.

The **.edu rule is enabled by default alongside the school-learning list**, as a separate permission. It allows every domain ending in .edu and its subdomains in both filtering modes. It does not insert thousands of university names into the list. `harvard.edu`, `mit.edu`, and `example.edu` are not list entries, but their .edu suffix matches this separate rule. Disable **Allow every .edu domain** to restrict .edu access to specifically listed learning services such as `scratch.mit.edu` and `phet.colorado.edu`. The rule does not match `.edu.au`, `school.edu.example.com`, or .edu text in a URL path. Both permissions have their own toggle; custom blocks override either one.

Open **Education list** to browse, search by platform/resource name or domain, filter categories, download the text list, or disable the bundle. Searches for `iready` also match `i-Ready`. Frequently used school tools appear first. Custom exceptions remain separate. The dashboard count covers listed domains; it does not attempt to count every .edu website. Policies exported before the .edu setting existed use its enabled default; exported policies containing `eduAllowed` preserve that explicit preference.

In **Only allow approved websites** mode, the active school list, enabled .edu rule, and custom allow rules determine what is available; other sites are blocked. In **Block selected websites** mode, an unlisted site remains available unless a custom block or selected category blocks it. Merely being absent from the whitelist does not block a site in blocklist mode.

The list combines named school learning products with website hosts linked from TeachersFirst classroom-resource reviews. Entries contain their review or provider-documentation links in `education-list.json`. IXL and i-Ready supporting hosts follow their current published network requirements. Their dedicated roots include their login subdomains; shared providers use specific documented hosts instead of blanket `cloudfront.net`, `amazonaws.com`, or `box.com` permissions. This extension filters page/iframe navigation, not every image/script request, so many network-support domains do not need special rules.

All included entries returned DNS records on October 13, 2026, either at the listed host or an official representative subdomain. 42 unresolved candidates were excluded. DNS resolution does not verify every page's content, and TeachersFirst lists include resources useful to teachers as well as students. This is a broad classroom-resource starting point, not a guarantee that every page on every listed domain is appropriate for every age. District-specific sign-in or newly changed provider hosts may still need custom allow rules. Authenticated student sessions have not been tested in this workspace.

Files:
- `education-list.json`: names, categories, aliases, source URLs, and screening details.
- `education-list.mjs`: packaged domains used by the network rules.
- `education-whitelist.txt`: one explicit domain per line.

Sources:
- TeachersFirst resource directory: https://teachersfirst.com/classroom_resources.cfm
- IXL network requirements: https://ca.ixl.com/help-centre/article/4585073/which_domains_should_my_school_network_allow_in_order_to_use_ixl
- i-Ready July 2026 system requirements: https://cdn.i-ready.com/instruction/content/system-check/iReady_System_Requirements.pdf

## Filtering behavior

- Domain rules include subdomains.
- Custom allow rules take priority (100).
- Custom blocks override the bundled school list (70).
- The school list and .edu rule allow their matching destinations (50).
- Category and allowlist-only catch-all blocks apply last (10).
- The policy checker uses the same priority order.
- Games, social media, streaming, and shopping categories are small visible domain lists, not full internet classifiers.
- Policy import/export, reset, a toolbar popup, and a blocked page are included.
- Up to 10,000 custom domain rules can accompany the bundle.

Changes apply to subsequent network navigations. Refresh or open a new tab when testing. Already loaded content is not removed. Only HTTP/HTTPS page and embedded-frame navigation is filtered. Other browsers/apps and general network traffic are outside this extension's scope. Teacher viewing is a separate monitored class session that requires an active shared screen; Chrome’s native capture prompt still starts the stream.

## School-managed deployment

A personal unpacked installation can be edited, disabled, or removed by its user. Administrative enforcement requires enterprise extension distribution/force-install and appropriate Chrome device/browser policies.

The manifest declares `managed-schema.json`. Supply the keys shown in `managed-policy.example.json` through Chrome's managed extension-policy mechanism for the deployed extension ID. The example file does not activate management by itself. Verify delivered values at `chrome://policy`.

- `LockConfiguration: true`: ignore local policy and overlay managed values on shipped defaults.
- `Enabled`: enable filtering.
- `Mode`: `blocklist` or `allowlist`.
- `Categories`: any of `games`, `social`, `video`, `shopping`.
- `BlockedDomains`, `AllowedDomains`: domain-only arrays without paths or ports.
- `EducationWhitelistEnabled`: enable or disable the school learning list.
- `EduDomainsAllowed`: enable or disable the separate .edu permission.

Any managed filtering key disables local dashboard editing. Supply all eight filtering keys for complete administrator control. Locking the dashboard does not prevent removing the extension. Test deployment in your managed environment before rollout. The teacher viewer shows all live class screens and synchronizes that class’s temporary website allowlist. The normal district policy remains local/managed per extension; central fleet administration is not included.

## Privacy and permissions

Settings stay in `chrome.storage.local`; administrative values come from `chrome.storage.managed`. The website filter does not upload browsing URLs or collect browsing history. During a restricted class it reads current tab URLs locally to redirect pages outside the teacher’s list. Screen sharing sends a student-selected video stream to the approved teacher and holds display names/class metadata temporarily in the pairing server. The application does not record video. There are no analytics endpoints or content scripts. HTTP/HTTPS host permissions allow Chrome to redirect blocked navigations and connect to your configured viewing server. The `desktopCapture` permission opens Chrome’s native screen picker before monitored class entry. The extension cannot bypass that prompt. Declining or ending capture ends the class session.

## Development and preview

The source is plain HTML/CSS/JavaScript with no build step. `policy.mjs` defines normalization, network-rule compilation, and the tester. `background.mjs` owns writes and managed-policy enforcement.

Serve this directory over localhost to preview `index.html`. Web previews save separate local settings and do not block websites. Open the dashboard through the extension to apply real filtering. Chrome-installation/live network blocking still needs verification on the target browser/device.

Chrome references:
- https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest
- https://developer.chrome.com/docs/extensions/reference/api/storage
- https://developer.chrome.com/docs/extensions/reference/manifest/storage

## Add 1,000+ students at once

Open **Screen viewing → Open district roster**. The server administrator must set a separate `CLASSGUARD_ADMIN_KEY` (at least 24 characters, different from the teacher key). Connect with that key and your school server address.

1. Download the CSV template, or export your roster with `student_id,name,email,class_group` columns. Email is optional when student ID is present. `first_name,last_name` can replace `name`; email can serve as the identifier if student ID is missing. Use semicolons for multiple class groups.
2. Upload the UTF-8 CSV (up to 4 MB and 20,000 students). Preview it, fix any errors, then select **Import students**. Imports add or update matching IDs, keeping other students. Optional automatic grouping creates sections of up to 30 for students without groups.
3. Select the replacement confirmation and **Generate & download enrollment codes**. This replaces previous codes for future entries and downloads one code/link per student. Give each student only their own row through your existing school system. Keep the full export private.
4. In the installed extension’s student sharing page, enter the school server and personal code, then **Save enrollment**. The installed extension saves it on that device. Browser previews keep it only in tab session storage and cannot join website-restricted classes. The web enrollment link fills the code using a URL fragment, then removes it from the address bar; it does not install the extension.
5. Teachers enter their teacher key, select **Load class groups**, choose a group, and start their period. Enrolled students refresh their classes and join. Registered members are approved automatically; Chrome’s picker and live sharing remain required.

The roster has a 20,000-student limit; live viewing remains up to 30 per classroom. Auto-created sections are convenience groups: supply actual class memberships for your school’s timetable. Reimporting identical data keeps existing codes and groups when automatic grouping is enabled. Supplied class memberships replace that student’s previous memberships. A preview expires if another administrator updates the roster.

Roster import does not install the extension on district devices. Follow `classguard-server/BULK-ENROLLMENT.md` for Google Admin rollout and enrollment details. This package has not been published in the Chrome Web Store and does not include SIS sync, Google SSO, or email delivery.

## HTML game inspection

Enabled by default in version 1.9. Open **Website rules → HTML game inspection** to enable/disable it or set **Approved activity domains** (up to 200 domains, including subdomains). Domain allow rules, the education list, and the .edu rule do not exempt HTML content from inspection. A trusted activity exception skips content inspection while ordinary district and class domain restrictions still apply. Use narrowly scoped exceptions for approved educational games or coding lessons that run game engines.

The installed extension reads accessible page DOM locally after loading and in matching embedded frames. It looks for known game embeds, recognized engine script names or inline initialization together with a canvas, and combinations of game titles, play controls, score/lives displays, and interactive surfaces. A canvas, game name, score, or the word “games” alone does not trigger a block. The scanner observes DOM changes, limits scan frequency, and periodically rechecks pages and current policy. It does not execute code found in HTML or fetch external script bodies. Inline JSON and other non-executable script types are excluded from engine detection.

When strong signals are detected, the worker checks the sender, current tab, current policy, and the still-live originating document before redirecting the entire tab to the blocked page. A game detected in a matching child frame also blocks its containing tab. The blocked page explains the detected signal types. Content scripts cannot save policy, read classroom credentials, or cancel a class restriction.

All classification happens on the device. Full HTML, text, input values, and URLs are not sent to a remote classifier or the school server. Only boolean/count signals pass to the extension worker; short reason codes stay in Chrome session storage for the blocked-page explanation (displayed for up to two minutes, cleared on navigation/tab close or browser exit). No browsing history or HTML archive is created.

Managed settings: `ContentInspectionEnabled` and `InspectionExceptionDomains`. Administrators can lock them using the existing managed-policy mechanism. Pausing ordinary filtering pauses inspection, except when a website-restricted class period is still active. Disabling the separate HTML inspection setting stops these scans; domain and class rules continue to apply.

This is a deterministic heuristic detector, not GoGuardian’s or Securly’s proprietary classifier. It may miss obfuscated games, unusual engines, closed shadow DOM content, inaccessible frames, non-HTTP documents, and games without detectable markup. It can also flag a legitimate interactive learning activity; review it and add a narrow exception where appropriate. Because inspection happens after a page loads, code may run briefly before redirection. Keep domain rules and class allowlists for access prevention. Native Chrome protected pages, file URLs, and other applications are outside this scanner’s scope.

Classifier and worker integration tests pass. Browser QA used the real scanner on synthetic HTML with a chart and a game inserted after load, through an explicitly labeled test bridge. This does not replace a test of the installed extension on actual managed Chromebooks.

Chrome references: [content-script registration and frame behavior](https://developer.chrome.com/docs/extensions/reference/manifest/content-scripts), [runtime message sender identity](https://developer.chrome.com/docs/extensions/reference/api/runtime#type-MessageSender).