@socwarden/browser 1.0.0-alpha.1

package/README.md

@@ -0,0 +1,73 @@
+# @socwarden/browser
+
+Lightweight browser SDK for SOCWarden client-side context collection. Under 3KB minified.
+
+## Installation
+
+```bash
+npm install @socwarden/browser
+```
+
+Or include via CDN (UMD):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@socwarden/browser/dist/socwarden.min.js"></script>
+```
+
+## Modes
+
+### Relay Mode (recommended)
+
+Collects client context and attaches it as a `X-SOCWarden-Context` header on your app's own requests. Your server-side SDK (e.g. `@socwarden/laravel`) merges this into events automatically.
+
+```js
+import { SOCWardenBrowser } from '@socwarden/browser';
+
+const sw = new SOCWardenBrowser({ mode: 'relay' });
+sw.installRelay();
+// All subsequent fetch() and XMLHttpRequest calls include the context header.
+```
+
+### Direct Mode
+
+Sends events directly to the SOCWarden ingestor. Useful for SPAs without a backend.
+
+```js
+import { SOCWardenBrowser } from '@socwarden/browser';
+
+const sw = new SOCWardenBrowser({
+  mode: 'direct',
+  apiKey: 'sw_live_xxxxxxxxxxxxxxxxxxxx',
+  endpoint: 'https://ingest.socwarden.io',
+});
+
+await sw.track('auth.login.success', { user_id: '42' });
+```
+
+## Collected Context
+
+| Field | Source |
+|-------|--------|
+| `timezone` | `Intl.DateTimeFormat().resolvedOptions().timeZone` |
+| `language` | `navigator.language` |
+| `platform` | `navigator.platform` |
+| `screen` | `screen.width` x `screen.height` |
+| `viewport` | `window.innerWidth` x `window.innerHeight` |
+| `color_depth` | `screen.colorDepth` |
+| `cookie_enabled` | `navigator.cookieEnabled` |
+| `do_not_track` | `navigator.doNotTrack === '1'` |
+| `connection_type` | `navigator.connection?.effectiveType` |
+| `downlink` | `navigator.connection?.downlink` |
+
+## Custom Header Name
+
+```js
+const sw = new SOCWardenBrowser({
+  mode: 'relay',
+  headerName: 'X-My-Custom-Header',
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+/**
+ * SOCWarden Browser SDK
+ *
+ * Lightweight client-side context collection (<3KB minified).
+ * Two modes:
+ *   - relay:  Collects context and injects it as X-SOCWarden-Context header
+ *             on the app's own fetch/XHR requests. Server-side SDK merges it.
+ *   - direct: Sends events straight to the SOCWarden ingestor (for SPAs).
+ */
+interface SOCWardenBrowserConfig {
+    /** Operating mode. */
+    mode: 'relay' | 'direct';
+    /** API key — required for direct mode. */
+    apiKey?: string;
+    /** Ingestor endpoint URL — required for direct mode. */
+    endpoint?: string;
+    /** Header name used in relay mode. Default: X-SOCWarden-Context */
+    headerName?: string;
+    /**
+     * D5 FIX (GDPR): Controls how much device data is collected.
+     *
+     * - 'none'  — collect nothing (SDK is effectively disabled for context).
+     * - 'basic' — collect only page URL, referrer, browser language, viewport size.
+     *             No fingerprinting data. **Default.**
+     * - 'full'  — collect all data including WebGL GPU renderer, hardware
+     *             concurrency, device memory, and screen resolution.
+     *             Only use with explicit user consent.
+     */
+    consentLevel?: 'none' | 'basic' | 'full';
+}
+interface ClientContext {
+    timezone: string;
+    language: string;
+    languages: string[];
+    touch: boolean;
+    platform: string;
+    screen: string;
+    viewport: string;
+    color_depth: number;
+    cookie_enabled: boolean;
+    do_not_track: boolean;
+    connection_type: string | undefined;
+    downlink: number | undefined;
+    gpu_renderer: string | undefined;
+    device_memory: number | undefined;
+    cpu_cores: number | undefined;
+    page_url: string;
+    page_referrer: string;
+    page_title: string;
+}
+declare class SOCWardenBrowser {
+    private readonly config;
+    private readonly headerName;
+    private ctx;
+    private encoded;
+    private _backedOff;
+    private _backoffTimer;
+    constructor(config: SOCWardenBrowserConfig);
+    /** Return the current client context snapshot (respects configured consentLevel). */
+    collectContext(): ClientContext;
+    /**
+     * Relay mode — monkey-patch `fetch` and `XMLHttpRequest` so that every
+     * outgoing request automatically carries the context header.
+     */
+    installRelay(): void;
+    /**
+     * Direct mode — POST an event to the SOCWarden ingestor.
+     * Never throws — errors are silently logged via console.warn.
+     *
+     * @param event  Event type, e.g. "auth.login.success"
+     * @param metadata  Arbitrary key-value metadata to attach
+     */
+    track(event: string, metadata?: Record<string, any>): Promise<void>;
+}
+
+export { type ClientContext, SOCWardenBrowser, type SOCWardenBrowserConfig, SOCWardenBrowser as default };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * SOCWarden Browser SDK
+ *
+ * Lightweight client-side context collection (<3KB minified).
+ * Two modes:
+ *   - relay:  Collects context and injects it as X-SOCWarden-Context header
+ *             on the app's own fetch/XHR requests. Server-side SDK merges it.
+ *   - direct: Sends events straight to the SOCWarden ingestor (for SPAs).
+ */
+interface SOCWardenBrowserConfig {
+    /** Operating mode. */
+    mode: 'relay' | 'direct';
+    /** API key — required for direct mode. */
+    apiKey?: string;
+    /** Ingestor endpoint URL — required for direct mode. */
+    endpoint?: string;
+    /** Header name used in relay mode. Default: X-SOCWarden-Context */
+    headerName?: string;
+    /**
+     * D5 FIX (GDPR): Controls how much device data is collected.
+     *
+     * - 'none'  — collect nothing (SDK is effectively disabled for context).
+     * - 'basic' — collect only page URL, referrer, browser language, viewport size.
+     *             No fingerprinting data. **Default.**
+     * - 'full'  — collect all data including WebGL GPU renderer, hardware
+     *             concurrency, device memory, and screen resolution.
+     *             Only use with explicit user consent.
+     */
+    consentLevel?: 'none' | 'basic' | 'full';
+}
+interface ClientContext {
+    timezone: string;
+    language: string;
+    languages: string[];
+    touch: boolean;
+    platform: string;
+    screen: string;
+    viewport: string;
+    color_depth: number;
+    cookie_enabled: boolean;
+    do_not_track: boolean;
+    connection_type: string | undefined;
+    downlink: number | undefined;
+    gpu_renderer: string | undefined;
+    device_memory: number | undefined;
+    cpu_cores: number | undefined;
+    page_url: string;
+    page_referrer: string;
+    page_title: string;
+}
+declare class SOCWardenBrowser {
+    private readonly config;
+    private readonly headerName;
+    private ctx;
+    private encoded;
+    private _backedOff;
+    private _backoffTimer;
+    constructor(config: SOCWardenBrowserConfig);
+    /** Return the current client context snapshot (respects configured consentLevel). */
+    collectContext(): ClientContext;
+    /**
+     * Relay mode — monkey-patch `fetch` and `XMLHttpRequest` so that every
+     * outgoing request automatically carries the context header.
+     */
+    installRelay(): void;
+    /**
+     * Direct mode — POST an event to the SOCWarden ingestor.
+     * Never throws — errors are silently logged via console.warn.
+     *
+     * @param event  Event type, e.g. "auth.login.success"
+     * @param metadata  Arbitrary key-value metadata to attach
+     */
+    track(event: string, metadata?: Record<string, any>): Promise<void>;
+}
+
+export { type ClientContext, SOCWardenBrowser, type SOCWardenBrowserConfig, SOCWardenBrowser as default };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var u=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var _=(t,e)=>{for(var n in e)u(t,n,{get:e[n],enumerable:!0})},y=(t,e,n,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of h(e))!m.call(t,o)&&o!==n&&u(t,o,{get:()=>e[o],enumerable:!(r=g(e,o))||r.enumerable});return t};var w=t=>y(u({},"__esModule",{value:!0}),t);var x={};_(x,{SOCWardenBrowser:()=>d,default:()=>k});module.exports=w(x);function v(){try{let t=document.createElement("canvas"),e=t.getContext("webgl")||t.getContext("experimental-webgl");if(e&&e instanceof WebGLRenderingContext){let n=e.getExtension("WEBGL_debug_renderer_info");if(n)return e.getParameter(n.UNMASKED_RENDERER_WEBGL)}}catch{}}var b=/^[a-z][a-z0-9]{0,29}(\.[a-z][a-z0-9_]{0,29}){1,3}$/;function C(t){try{let e=new URL(t),n=["token","key","password","secret","code","api_key","apikey","access_token","refresh_token"];for(let r of n)e.searchParams.has(r)&&e.searchParams.set(r,"[REDACTED]");return e.toString()}catch{return t}}function p(t="basic"){if(t==="none")return{timezone:"",language:"",languages:[],touch:!1,platform:"",screen:"",viewport:"",color_depth:0,cookie_enabled:!1,do_not_track:!1,connection_type:void 0,downlink:void 0,gpu_renderer:void 0,device_memory:void 0,cpu_cores:void 0,page_url:"",page_referrer:"",page_title:""};let e={timezone:Intl.DateTimeFormat().resolvedOptions().timeZone,language:navigator.language,languages:Array.from(navigator.languages||[navigator.language]),touch:!1,platform:"",screen:"",viewport:`${window.innerWidth}x${window.innerHeight}`,color_depth:0,cookie_enabled:!1,do_not_track:navigator.doNotTrack==="1",connection_type:void 0,downlink:void 0,gpu_renderer:void 0,device_memory:void 0,cpu_cores:void 0,page_url:C(location.href),page_referrer:document.referrer,page_title:document.title};return t!=="full"?e:{...e,touch:navigator.maxTouchPoints>0,platform:navigator.platform,screen:`${screen.width}x${screen.height}`,color_depth:screen.colorDepth,cookie_enabled:navigator.cookieEnabled,connection_type:navigator.connection?.effectiveType,downlink:navigator.connection?.downlink,gpu_renderer:v(),device_memory:navigator.deviceMemory,cpu_cores:navigator.hardwareConcurrency}}function f(t){return btoa(JSON.stringify(t))}var d=class{constructor(e){this._backedOff=!1;this._backoffTimer=null;if(e.mode==="direct"){if(!e.apiKey)throw new Error("SOCWarden: apiKey is required in direct mode");if(!e.endpoint)throw new Error("SOCWarden: endpoint is required in direct mode");if(e.endpoint&&!e.endpoint.startsWith("https://")){if(!(e.endpoint.startsWith("http://localhost")||e.endpoint.startsWith("http://127.0.0.1")))throw new Error("SOCWarden: endpoint must use HTTPS. API keys must not be transmitted in cleartext.");console.warn("[SOCWarden] WARNING: Endpoint is using HTTP. API keys will be transmitted in cleartext.")}}this.config=e,this.headerName=e.headerName??"X-SOCWarden-Context",this.ctx=p(e.consentLevel??"basic"),this.encoded=f(this.ctx)}collectContext(){return this.ctx=p(this.config.consentLevel??"basic"),this.encoded=f(this.ctx),this.ctx}installRelay(){let e=this.headerName,n=()=>this.encoded,r=window.fetch;window.fetch=function(c,a){a=a??{};let l=new Headers(a.headers);return l.has(e)||l.set(e,n()),a.headers=l,r.call(window,c,a)};let o=XMLHttpRequest.prototype.open,i=XMLHttpRequest.prototype.send;XMLHttpRequest.prototype.open=function(...s){return this.__socwardenPatched=!1,o.apply(this,s)},XMLHttpRequest.prototype.send=function(...s){if(!this.__socwardenPatched){try{this.setRequestHeader(e,n())}catch{}this.__socwardenPatched=!0}return i.apply(this,s)}}async track(e,n){if(this.config.mode!=="direct"){console.warn("SOCWarden: track() is only available in direct mode");return}if(!b.test(e)){console.warn(`[SOCWarden] Invalid event type format, dropping event: "${e}". Event types must match ^[a-z][a-z0-9]{0,29}(\\.[a-z][a-z0-9_]{0,29}){1,3}$`);return}if(this._backedOff){console.warn("SOCWarden: rate-limited, skipping event");return}try{let r=this.config.endpoint.replace(/\/+$/,""),o={event:e,source:"browser",metadata:n??{},context:this.ctx,timestamp:new Date().toISOString()},i=await fetch(`${r}/v1/events`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.config.apiKey}`},body:JSON.stringify(o),keepalive:!0});if(i.status===429){this._backedOff=!0;let s=i.headers?.get?.("Retry-After"),c=60;if(s){let a=parseInt(s,10);!isNaN(a)&&a>0&&(c=Math.min(a,300))}this._backoffTimer=setTimeout(()=>{this._backedOff=!1,this._backoffTimer=null},c*1e3),console.warn(`SOCWarden: rate-limited, backing off for ${c}s`);return}if(!i.ok&&i.status!==202){console.warn(`SOCWarden: ingestor responded with ${i.status}`);return}}catch(r){console.warn("SOCWarden: failed to send event",r);return}}},k=d;0&&(module.exports={SOCWardenBrowser});

package/dist/index.mjs

@@ -0,0 +1 @@
+function f(){try{let t=document.createElement("canvas"),e=t.getContext("webgl")||t.getContext("experimental-webgl");if(e&&e instanceof WebGLRenderingContext){let n=e.getExtension("WEBGL_debug_renderer_info");if(n)return e.getParameter(n.UNMASKED_RENDERER_WEBGL)}}catch{}}var g=/^[a-z][a-z0-9]{0,29}(\.[a-z][a-z0-9_]{0,29}){1,3}$/;function h(t){try{let e=new URL(t),n=["token","key","password","secret","code","api_key","apikey","access_token","refresh_token"];for(let o of n)e.searchParams.has(o)&&e.searchParams.set(o,"[REDACTED]");return e.toString()}catch{return t}}function u(t="basic"){if(t==="none")return{timezone:"",language:"",languages:[],touch:!1,platform:"",screen:"",viewport:"",color_depth:0,cookie_enabled:!1,do_not_track:!1,connection_type:void 0,downlink:void 0,gpu_renderer:void 0,device_memory:void 0,cpu_cores:void 0,page_url:"",page_referrer:"",page_title:""};let e={timezone:Intl.DateTimeFormat().resolvedOptions().timeZone,language:navigator.language,languages:Array.from(navigator.languages||[navigator.language]),touch:!1,platform:"",screen:"",viewport:`${window.innerWidth}x${window.innerHeight}`,color_depth:0,cookie_enabled:!1,do_not_track:navigator.doNotTrack==="1",connection_type:void 0,downlink:void 0,gpu_renderer:void 0,device_memory:void 0,cpu_cores:void 0,page_url:h(location.href),page_referrer:document.referrer,page_title:document.title};return t!=="full"?e:{...e,touch:navigator.maxTouchPoints>0,platform:navigator.platform,screen:`${screen.width}x${screen.height}`,color_depth:screen.colorDepth,cookie_enabled:navigator.cookieEnabled,connection_type:navigator.connection?.effectiveType,downlink:navigator.connection?.downlink,gpu_renderer:f(),device_memory:navigator.deviceMemory,cpu_cores:navigator.hardwareConcurrency}}function p(t){return btoa(JSON.stringify(t))}var l=class{constructor(e){this._backedOff=!1;this._backoffTimer=null;if(e.mode==="direct"){if(!e.apiKey)throw new Error("SOCWarden: apiKey is required in direct mode");if(!e.endpoint)throw new Error("SOCWarden: endpoint is required in direct mode");if(e.endpoint&&!e.endpoint.startsWith("https://")){if(!(e.endpoint.startsWith("http://localhost")||e.endpoint.startsWith("http://127.0.0.1")))throw new Error("SOCWarden: endpoint must use HTTPS. API keys must not be transmitted in cleartext.");console.warn("[SOCWarden] WARNING: Endpoint is using HTTP. API keys will be transmitted in cleartext.")}}this.config=e,this.headerName=e.headerName??"X-SOCWarden-Context",this.ctx=u(e.consentLevel??"basic"),this.encoded=p(this.ctx)}collectContext(){return this.ctx=u(this.config.consentLevel??"basic"),this.encoded=p(this.ctx),this.ctx}installRelay(){let e=this.headerName,n=()=>this.encoded,o=window.fetch;window.fetch=function(s,r){r=r??{};let d=new Headers(r.headers);return d.has(e)||d.set(e,n()),r.headers=d,o.call(window,s,r)};let c=XMLHttpRequest.prototype.open,a=XMLHttpRequest.prototype.send;XMLHttpRequest.prototype.open=function(...i){return this.__socwardenPatched=!1,c.apply(this,i)},XMLHttpRequest.prototype.send=function(...i){if(!this.__socwardenPatched){try{this.setRequestHeader(e,n())}catch{}this.__socwardenPatched=!0}return a.apply(this,i)}}async track(e,n){if(this.config.mode!=="direct"){console.warn("SOCWarden: track() is only available in direct mode");return}if(!g.test(e)){console.warn(`[SOCWarden] Invalid event type format, dropping event: "${e}". Event types must match ^[a-z][a-z0-9]{0,29}(\\.[a-z][a-z0-9_]{0,29}){1,3}$`);return}if(this._backedOff){console.warn("SOCWarden: rate-limited, skipping event");return}try{let o=this.config.endpoint.replace(/\/+$/,""),c={event:e,source:"browser",metadata:n??{},context:this.ctx,timestamp:new Date().toISOString()},a=await fetch(`${o}/v1/events`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.config.apiKey}`},body:JSON.stringify(c),keepalive:!0});if(a.status===429){this._backedOff=!0;let i=a.headers?.get?.("Retry-After"),s=60;if(i){let r=parseInt(i,10);!isNaN(r)&&r>0&&(s=Math.min(r,300))}this._backoffTimer=setTimeout(()=>{this._backedOff=!1,this._backoffTimer=null},s*1e3),console.warn(`SOCWarden: rate-limited, backing off for ${s}s`);return}if(!a.ok&&a.status!==202){console.warn(`SOCWarden: ingestor responded with ${a.status}`);return}}catch(o){console.warn("SOCWarden: failed to send event",o);return}}},m=l;export{l as SOCWardenBrowser,m as default};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@socwarden/browser",
+  "version": "1.0.0-alpha.1",
+  "description": "Lightweight browser SDK for SOCWarden client-side context collection",
+  "main": "dist/socwarden.min.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --minify --dts --global-name SOCWarden",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "npx tsx --test src/__tests__/*.test.ts"
+  },
+  "keywords": [
+    "socwarden",
+    "security",
+    "observability",
+    "browser",
+    "sdk"
+  ],
+  "author": "SOCWarden",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.4.0"
+  }
+}