@x47base/pocketbase-addon 0.1.0

package/security/state.go

@@ -0,0 +1,116 @@
+package security
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"maps"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+type checkpoint struct {
+	Version   int               `json:"version"`
+	Revision  uint64            `json:"revision"`
+	Policy    Config            `json:"policy"`
+	Incidents []Incident        `json:"incidents"`
+	Actions   map[string]Action `json:"actions"`
+	NextID    uint64            `json:"nextId"`
+}
+
+func (s *Service) loadState() {
+	if s.config.StatePath == "" {
+		return
+	}
+	file, err := os.Open(s.config.StatePath)
+	if os.IsNotExist(err) {
+		return
+	}
+	if err != nil {
+		s.storageError = true
+		return
+	}
+	defer file.Close()
+	raw, err := io.ReadAll(io.LimitReader(file, (1<<20)+1))
+	if err != nil || len(raw) > 1<<20 {
+		s.storageError = true
+		return
+	}
+	var state checkpoint
+	if json.Unmarshal(raw, &state) != nil || state.Version != 1 || state.Revision == 0 || len(state.Incidents) > 256 || len(state.Actions) > 6 || state.Policy.Validate() != nil {
+		s.storageError = true
+		return
+	}
+	for _, incident := range state.Incidents {
+		if !validFamily(incident.Family) || incident.ID > state.NextID || len(incident.Phase) > 32 {
+			s.storageError = true
+			return
+		}
+	}
+	for family, action := range state.Actions {
+		if !validFamily(family) || family != action.Family || len(action.Reason) > 200 {
+			s.storageError = true
+			return
+		}
+		if !action.ExpiresAt.After(time.Now()) || action.ExpiresAt.After(time.Now().Add(15*time.Minute)) {
+			delete(state.Actions, family)
+		}
+	}
+	state.Policy.OperatorPeers = s.config.OperatorPeers
+	state.Policy.StatePath = s.config.StatePath
+	state.Policy.Mode = s.config.Mode
+	s.config = state.Policy
+	s.revision = state.Revision
+	s.incidents = state.Incidents
+	s.actions = state.Actions
+	s.nextID = state.NextID
+	if s.actions == nil {
+		s.actions = map[string]Action{}
+	}
+}
+func (s *Service) persist() {
+	s.journalMu.Lock()
+	defer s.journalMu.Unlock()
+	s.mu.Lock()
+	path := s.config.StatePath
+	state := checkpoint{Version: 1, Revision: s.revision, Policy: cloneConfig(s.config), Incidents: append([]Incident{}, s.incidents...), Actions: maps.Clone(s.actions), NextID: s.nextID}
+	s.mu.Unlock()
+	if path == "" {
+		return
+	}
+	raw, err := json.Marshal(state)
+	if err == nil && len(raw) > 1<<20 {
+		err = errors.New("state exceeds size limit")
+	}
+	if err == nil {
+		err = os.MkdirAll(filepath.Dir(path), 0700)
+	}
+	if err == nil {
+		var file *os.File
+		file, err = os.CreateTemp(filepath.Dir(path), ".security-state-*")
+		if err == nil {
+			defer os.Remove(file.Name())
+			defer file.Close()
+			if _, err = file.Write(raw); err == nil {
+				err = file.Sync()
+			}
+			if closeErr := file.Close(); err == nil {
+				err = closeErr
+			}
+			if err == nil {
+				err = os.Rename(file.Name(), path)
+			}
+		}
+	}
+	s.mu.Lock()
+	s.storageError = err != nil
+	s.mu.Unlock()
+}
+func validFamily(family string) bool {
+	switch family {
+	case "auth", "reads", "writes", "files", "realtime", "other":
+		return true
+	}
+	return false
+}

package/security/ui/dashboard.css

@@ -0,0 +1,4 @@
+.pb-security{padding:28px 32px;overflow:auto;display:block!important;--sec-bg:light-dark(#fff,#22252c);--sec-text:light-dark(#222832,#e7eaf0);--sec-muted:light-dark(#616b79,#b2bac7);--sec-line:light-dark(#dce1e7,#434956);--sec-soft:light-dark(#f5f7fa,#2c3039);color:var(--sec-text)}
+.pb-security *{box-sizing:border-box}.pb-security h1{font-size:28px;margin:2px 0 8px}.pb-security h2{font-size:18px;margin:0 0 12px}.pb-security p{line-height:1.5}.pb-security .sec-heading{display:flex;justify-content:space-between;gap:24px;align-items:center}.pb-security .sec-eyebrow{font-size:11px;letter-spacing:.13em;font-weight:600;color:var(--sec-muted);margin:0}.pb-security .sec-refresh{display:flex;flex-direction:column;gap:8px;align-items:end;white-space:nowrap}.pb-security [data-updated],.pb-security .sec-muted,.pb-security small{color:var(--sec-muted);font-size:13px}.pb-security .sec-tabs{display:flex;gap:8px;border-bottom:1px solid var(--sec-line);margin:20px 0}.pb-security .sec-tab{padding:12px 18px;border:0;background:transparent;color:inherit;font:inherit;cursor:pointer;border-bottom:3px solid transparent}.pb-security .sec-tab[aria-current=page]{border-bottom-color:light-dark(#315cbf,#8fb4ff);font-weight:600}.pb-security button:focus-visible,.pb-security input:focus-visible,.pb-security select:focus-visible,.pb-security textarea:focus-visible,.pb-security summary:focus-visible{outline:3px solid #749cfa;outline-offset:3px}.pb-security .sec-notice{padding:12px 16px;background:var(--sec-soft);border-radius:8px;margin:12px 0}.pb-security .sec-error{background:light-dark(#fff1ef,#482c2b);color:light-dark(#982d22,#ffc1b9)}.pb-security .sec-stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(165px,1fr));gap:16px;margin-bottom:20px}.pb-security .sec-stat{display:flex;flex-direction:column;gap:8px;padding:18px;border:1px solid var(--sec-line);border-radius:10px;background:var(--sec-bg)}.pb-security .sec-stat>span{font-size:13px;color:var(--sec-muted)}.pb-security .sec-stat strong{font-size:26px;font-weight:600;text-transform:capitalize}.pb-security .sec-columns{display:grid;grid-template-columns:1.4fr 1fr;gap:20px}.pb-security .sec-panel{padding:22px;background:var(--sec-bg);border:1px solid var(--sec-line);border-radius:10px;margin-bottom:20px}.pb-security .sec-chart{height:150px;display:flex;gap:3px;align-items:end;border-bottom:1px solid var(--sec-line);margin:20px 0}.pb-security .sec-bar{min-width:2px;max-width:28px;flex:1;background:#557bc5;display:flex;align-items:end;border-radius:3px 3px 0 0}.pb-security .sec-bar span{width:100%;background:#c79030}.pb-security .sec-facts{display:grid;grid-template-columns:auto 1fr;gap:12px 18px;font-size:14px}.pb-security dt{color:var(--sec-muted)}.pb-security dd{margin:0;overflow-wrap:anywhere}.pb-security .sec-context{color:var(--sec-muted);font-size:13px}.pb-security .sec-filters{display:flex;gap:18px;margin-bottom:20px}.pb-security .sec-field{display:flex;flex-direction:column;gap:8px;flex:1;min-width:0;margin:0 0 18px;font-size:14px}.pb-security .sec-field>span{font-weight:600}.pb-security input,.pb-security select,.pb-security textarea{display:block;width:100%;height:auto;min-height:42px;padding:10px 12px;border:1px solid var(--sec-line);background:var(--sec-bg);color:var(--sec-text);border-radius:6px;font:inherit;outline-offset:2px;appearance:auto}.pb-security .sec-empty{color:var(--sec-muted);padding-top:12px;padding-bottom:12px}.pb-security .sec-incident-heading{display:flex;gap:16px;align-items:start;justify-content:space-between}.pb-security .sec-badge{display:inline-block;font-size:12px;font-weight:600;padding:5px 10px;border-radius:30px;background:var(--sec-soft);white-space:nowrap}.pb-security .sec-active{background:light-dark(#fff0cf,#493c25);color:light-dark(#78510a,#ffd383)}.pb-security .sec-recovering{background:light-dark(#e7efff,#293a58);color:light-dark(#2c559c,#a9c8ff)}.pb-security .sec-resolved{background:light-dark(#e4f3e9,#263d2e);color:light-dark(#226c3f,#a4dfb8)}.pb-security details{margin:14px 0 20px}.pb-security summary{cursor:pointer;font-weight:600;padding:8px 0}.pb-security .sec-action{display:flex;align-items:center;gap:14px;flex-wrap:wrap;padding:12px 0;border-bottom:1px solid var(--sec-line)}.pb-security .sec-action>span:nth-child(2){flex:1;overflow-wrap:anywhere}.pb-security .sec-action-form{display:grid;grid-template-columns:1fr .7fr 1.4fr;gap:16px;align-items:start;margin-top:20px}.pb-security .sec-action-form>button{grid-column:1/-1;justify-self:start}.pb-security .sec-policy-fields{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:0 24px}.pb-security .sec-buttons{display:flex;gap:12px;flex-wrap:wrap}.pb-security .btn{max-width:100%;white-space:normal}
+@media(max-width:760px){.pb-security{padding:20px 16px}.pb-security .sec-heading{display:block}.pb-security .sec-refresh{align-items:start}.pb-security .sec-columns,.pb-security .sec-action-form,.pb-security .sec-policy-fields{grid-template-columns:1fr}.pb-security .sec-tabs{gap:0}.pb-security .sec-tab{padding:12px}.pb-security .sec-filters{display:block}.pb-security .sec-stats{grid-template-columns:repeat(2,minmax(0,1fr));gap:10px}.pb-security .sec-stat{padding:12px}.pb-security .sec-stat strong{font-size:22px}.pb-security .sec-panel{padding:16px}.pb-security .sec-facts{grid-template-columns:1fr;gap:6px}.pb-security dd{margin-bottom:10px}.pb-security input,.pb-security select,.pb-security textarea{font-size:16px}}
+.pb-security .sec-field input[type=checkbox]{appearance:auto;width:20px;height:20px;min-height:20px;margin:4px 0;justify-self:start}.pb-security .sec-field input[type=file]{height:auto;min-height:44px;padding:8px}.pb-security form>.btn{margin:4px 10px 12px 0}

package/security/ui/dashboard.js

@@ -0,0 +1,83 @@
+import { families, familyLabels, filterIncidents, percent, rate, timestamp, sessionRequest } from './model.js';
+
+const fields = [
+    ['requestsPerSecond','Global requests / second','Total admission rate before authentication.'],
+    ['burst','Global burst','Short bursts allowed across the instance.'],
+    ['identityPerSecond','Requests / identity / second','Verified users have separate budgets; anonymous clients share a source budget.'],
+    ['identityBurst','Identity burst','Short burst allowed for one identity.'],
+    ['maxConcurrent','Concurrent requests','Total in-flight application requests.'],
+    ['maxWrites','Concurrent write units','Batch operations reserve additional write units.'],
+    ['maxFiles','Concurrent file requests','Capacity reserved for file traffic.'],
+    ['maxRealtime','Realtime clients','Maximum tracked realtime connections.'],
+    ['maxSubscriptions','Subscriptions / client','Maximum subscriptions for one client.'],
+    ['maxSubscriptionsTotal','Total subscriptions','Aggregate tracked subscription capacity.'],
+    ['maxIdentities','Tracked identities','Excess identities share a bounded overflow bucket.'],
+];
+function el(tag, text, className) { const node = document.createElement(tag); if (text != null) node.textContent = text; if(className) node.className=className; return node; }
+function button(label, action, className='btn secondary') { const node=el('button',label,className);node.type='button';node.onclick=action;return node; }
+function badge(label, state) { return el('span',label,'sec-badge sec-'+state); }
+function labelField(label, input, hint) { const wrap=el('label',null,'sec-field');wrap.append(el('span',label),input);if(hint)wrap.append(el('small',hint));return wrap; }
+function select(options, value='') { const node=el('select');for(const [key,label] of options){const option=el('option',label);option.value=key;node.append(option);}node.value=options.some(([key])=>key===value)?value:(options[0]?.[0]||'');return node; }
+
+export function securityPage(app) {
+    let destroy=()=>{};
+    return t.div({className:'page pb-security',onmount:root=>{destroy=mount(root,app);},onunmount:()=>destroy()});
+}
+function mount(root, app) {
+    app.store.title='Security';
+    let view='overview', phase='', family='', status=null, incidents=[], draft=null, revision='', dirty=false, timer, busy=false, mutation=false;
+    let closed=false, sessionGone=false, lastRefresh=null, operatorNotice=false;
+    const session=()=>app.pb.authStore.token;
+    const client=sessionRequest((url,options)=>app.pb.send(url,options),session,()=>app.pb.authStore.clear());
+    root.innerHTML=`<div class="sec-heading"><div><p class="sec-eyebrow">INSTANCE PROTECTION</p><h1>Security</h1><p>Understand unusual activity and control how this instance handles traffic.</p></div><div class="sec-refresh"><button type="button" class="btn secondary" data-refresh>Refresh</button><span data-updated></span></div></div><div class="sec-notice" role="status" aria-live="polite" data-notice>Loading security data…</div><nav class="sec-tabs" aria-label="Security views"></nav><div data-content></div>`;
+    const content=root.querySelector('[data-content]'), notice=root.querySelector('[data-notice]'), updated=root.querySelector('[data-updated]');
+    const refreshButton=root.querySelector('[data-refresh]');
+    function message(text,error=false){if(closed)return;notice.textContent=text;notice.className='sec-notice'+(error?' sec-error':'');notice.hidden=!text;}
+    function checkSession(){if(!client.valid()){sessionGone=true;client.close();clearTimeout(timer);content.replaceChildren();message('Your session ended. Sign in to view security data.',true);return false;}return true;}
+    const unsubscribe=app.pb.authStore.onChange(()=>{if(!checkSession()) window.location.hash='#/login';});
+    function failure(error){if(closed||!checkSession())return;message(error.status===409?'The policy changed in another session. Your draft is preserved. Reload the current policy before saving.':error.status===403?'This connection is outside the management network. Ask the operator to configure access; dashboard login does not bypass this restriction.':error.message||'Security data could not be refreshed. Try again.',true);}
+    const tabs=root.querySelector('.sec-tabs');
+    function renderTabs(){tabs.replaceChildren();for(const [id,label] of [['overview','Overview'],['incidents','Incidents'],['protection','Protection']]){const b=button(label,()=>{view=id;render();},'sec-tab');b.setAttribute('aria-current',view===id?'page':'false');tabs.append(b);}}
+    function stats(parent, rows){const grid=el('div',null,'sec-stats');for(const [label,value,note] of rows){const card=el('section',null,'sec-stat');card.append(el('span',label),el('strong',String(value)),el('small',note));grid.append(card);}parent.append(grid);}
+    function render(){if(closed||!checkSession())return;renderTabs();content.replaceChildren();if(!status){content.append(el('p','Security data is not available yet.'));return;}if(view==='overview')overview();if(view==='incidents')incidentView();if(view==='protection')protection();}
+    function overview(){
+        const active=incidents.filter(i=>i.phase!=='resolved').length, last=status.traffic?.at(-1);
+        stats(content,[['Protection mode',status.mode,status.mode==='enforce'?'Configured limits can reject requests.':status.mode==='observe'?'Limits are observed without blocking.':'Admission protection and detection are disabled.'],['Open incidents',active,'Active or recovering suspected patterns.'],['Recent traffic',last?rate(last).toFixed(1)+' req/s':'Waiting','Last completed 10-second window.'],['Flagged requests',status.rejected,status.mode==='observe'?'Would be limited; requests still proceed.':'Admission decisions since this process started.']]);
+        const grid=el('div',null,'sec-columns');const traffic=el('section',null,'sec-panel');traffic.append(el('h2','Traffic over time'),el('p','Last 10 minutes · each bar is a 10-second window.','sec-muted'));
+        if(status.traffic?.length){const chart=el('div',null,'sec-chart');chart.setAttribute('role','img');chart.setAttribute('aria-label','Request volume for '+status.traffic.length+' recent ten-second windows');const peak=Math.max(1,...status.traffic.map(w=>w.count));for(const w of status.traffic){const bar=el('div',null,'sec-bar');bar.style.height=Math.max(2,100*w.count/peak)+'%';bar.title=timestamp(w.at)+': '+w.count+' requests, '+w.rejected+' flagged';const limited=el('span');limited.style.height=percent(w.rejected,w.count)+'%';bar.append(limited);chart.append(bar);}traffic.append(chart,el('p',timestamp(status.traffic[0].at)+' → '+timestamp(last.at)+' · Peak '+peak+' requests / window.','sec-muted'),el('p','Blue: requests · amber: flagged requests.','sec-muted'));if(last)traffic.append(el('p',`${last.count} requests · ${last.rejected} flagged · ${last.failures} failed · ${last.slow} slow in the latest window.`));}
+        else traffic.append(el('p',status.mode==='disabled'?'Enable observation to collect traffic windows.':'Waiting for the first 10-second observation window.','sec-empty'));
+        const health=el('section',null,'sec-panel');health.append(el('h2','Operational context'));const dl=el('dl',null,'sec-facts');for(const [key,value] of [['Detector','Heuristic patterns; no automatic blocks'],['Last evaluation',timestamp(status.lastEvaluated)],['Process started',timestamp(status.startedAt)],['Restart checkpoint',status.storageDegraded?'Write/read failure — recent state may be lost':status.checkpointEnabled?'Enabled (best effort)':'Not configured'],['Subscriptions',String(status.subscriptions)],['Active requests',Number(status.active?.ordinary||0)+Number(status.active?.realtime||0)+Number(status.active?.management||0)]])dl.append(el('dt',key),el('dd',String(value)));health.append(dl);grid.append(traffic,health);content.append(grid);
+        content.append(el('p','An incident is a suspected pattern, not proof of an attacker. Legitimate bursts, shared-source traffic and outages can produce the same signals.','sec-context'));
+        content.append(button('Review incidents',()=>{view='incidents';render();}));
+    }
+    function incidentView(){
+        const filters=el('div',null,'sec-filters');const phaseInput=select([['','All states'],['active','Active'],['recovering','Recovering'],['resolved','Resolved'],['unreviewed','Not acknowledged']],phase);phaseInput.onchange=()=>{phase=phaseInput.value;render();};const familyInput=select([['','All traffic'],...families.map(f=>[f,familyLabels[f]])],family);familyInput.onchange=()=>{family=familyInput.value;render();};filters.append(labelField('Incident state',phaseInput),labelField('Traffic family',familyInput));content.append(filters);
+        const rows=filterIncidents(incidents,phase,family);
+        if(!rows.length){const empty=el('section',null,'sec-panel sec-empty');empty.append(el('h2',incidents.length?'No matching incidents':'No incidents recorded'),el('p',incidents.length?'Change the filters to see other activity.':'Detection needs three consecutive suspicious 10-second windows. Short tests may not produce an incident.'));content.append(empty);return;}
+        const list=el('div',null,'sec-incidents');for(const item of rows){const card=el('article',null,'sec-panel');const heading=el('div',null,'sec-incident-heading');heading.append(el('h2',(familyLabels[item.family]||item.family)+' · #'+item.id),badge(item.phase,item.phase));card.append(heading,el('p','First seen '+timestamp(item.firstSeen)+' · Latest evidence '+timestamp(item.lastSeen),'sec-muted'));const o=item.evidence||{};stats(card,[['Requests',o.count||0,'Latest evidence window'],['Flagged',percent(o.rejected,o.count)+'%',(o.rejected||0)+' admission decisions'],['Failures',o.failures||0,(o.slow||0)+' slow requests']]);const details=el('details');details.append(el('summary','How to interpret this incident'),el('p','Compare traffic with client releases, database health and provider metrics. Acknowledging records review; it does not block traffic or resolve the detector state.'));card.append(details);const ack=button(item.acknowledged?'Acknowledged':'Acknowledge',()=>mutate(async()=>{await client.request('incidents/'+item.id+'/acknowledge',{method:'POST'});},'Incident acknowledged.'));ack.disabled=item.acknowledged||mutation;card.append(ack);list.append(card);}content.append(list);
+    }
+    function renderActions(list=content.querySelector('[data-sec-actions]')) {
+        if(!list||!status)return;list.replaceChildren();
+        for(const action of Object.values(status.actions||{})){const row=el('div',null,'sec-action');row.append(badge(familyLabels[action.family]||action.family,'active'),el('span',action.reason+' · Expires '+timestamp(action.expiresAt)),button('Cancel block',()=>mutate(()=>client.request('actions/'+action.family,{method:'DELETE'}),'Block cancelled.')));list.append(row);}
+        if(!Object.keys(status.actions||{}).length)list.append(el('p','No temporary blocks are configured.','sec-empty'));
+    }
+    function protection(){
+        const actions=el('section',null,'sec-panel');actions.append(el('h2','Temporary protection'),el('p','Family blocks reject all matching traffic, including legitimate users. They apply only in enforce mode.','sec-muted'));
+        const liveActions=el('div');liveActions.dataset.secActions='';actions.append(liveActions);renderActions(liveActions);
+        const form=el('form',null,'sec-action-form');const target=select(families.map(f=>[f,familyLabels[f]]));const minutes=el('input');minutes.type='number';minutes.min='1';minutes.max='15';minutes.value='1';minutes.required=true;const reason=el('input');reason.type='text';reason.maxLength=200;reason.required=true;form.append(labelField('Traffic to block',target),labelField('Duration (minutes)',minutes),labelField('Reason',reason));const submit=el('button','Apply temporary block','btn danger');submit.type='submit';submit.disabled=mutation;form.append(submit);form.onsubmit=e=>{e.preventDefault();mutate(()=>client.request('actions',{method:'POST',body:{family:target.value,reason:reason.value,expiresAt:new Date(Date.now()+Number(minutes.value)*60000).toISOString()}}),'Temporary block configured.');};actions.append(form);content.append(actions);
+        if(!draft){content.append(el('p','Policy is unavailable. Refresh to try again.'));return;}
+        const panel=el('section',null,'sec-panel');panel.append(el('h2','Protection policy'),el('p','Changes use revision '+revision+'. Unsaved settings are preserved while traffic refreshes.','sec-muted'));const policy=el('form');const mode=select([['disabled','Disabled'],['observe','Observe — measure only'],['enforce','Enforce — reject over budget']],draft.mode);mode.onchange=()=>{draft.mode=mode.value;dirty=true;};policy.append(labelField('Mode',mode));const fieldsGrid=el('div',null,'sec-policy-fields');for(const [key,label,hint] of fields){const input=el('input');input.type='number';input.required=true;input.min=key.includes('PerSecond')?'0.001':'1';input.max=key.includes('PerSecond')?'100000':'50000';input.step=key.includes('PerSecond')?'any':'1';input.value=draft[key];input.oninput=()=>{draft[key]=Number(input.value);dirty=true;};fieldsGrid.append(labelField(label,input,hint));}policy.append(fieldsGrid);
+        const networks=el('details');networks.append(el('summary','Advanced: proxy and management networks'));for(const [key,label] of [['trustedPeers','Trusted immediate proxy CIDRs'],['managementPeers','Management peer CIDRs']]){const input=el('textarea');input.rows=3;input.value=(draft[key]||[]).join('\n');input.oninput=()=>{draft[key]=input.value.split(/[\n,]/).map(v=>v.trim()).filter(Boolean);dirty=true;};networks.append(labelField(label,input,'One CIDR per line. Incorrect changes can block operator access.'));}policy.append(networks);const buttons=el('div',null,'sec-buttons');const save=el('button','Save policy','btn');save.type='submit';save.disabled=mutation;buttons.append(save,button('Discard draft and reload',()=>mutate(async()=>{const snapshot=await getPolicy();draft=snapshot.policy;revision=snapshot.revision;dirty=false;},'Current policy loaded.')));policy.append(buttons);policy.onsubmit=e=>{e.preventDefault();mutate(async()=>{await client.request('policy',{method:'PUT',headers:{'If-Match':revision},body:draft});const snapshot=await getPolicy();draft=snapshot.policy;revision=snapshot.revision;dirty=false;},'Policy saved.');};panel.append(policy);content.append(panel);
+    }
+    async function getPolicy(){return client.request('policy/snapshot');}
+    async function load(){
+        const nextStatus=await client.request('status');let all=[],after=0;
+        for(let page=0;page<3;page++){const response=await client.request('incidents?limit=100&after='+after);all.push(...response.items);after=response.nextCursor;if(!after)break;}
+        if(!draft){const snapshot=await getPolicy();draft=snapshot.policy;revision=snapshot.revision;}
+        if(!checkSession())return;status=nextStatus;incidents=all;lastRefresh=new Date();updated.textContent='Updated '+lastRefresh.toLocaleTimeString();
+    }
+    async function refresh(manual=false){if(busy||mutation||closed||!checkSession())return;busy=true;refreshButton.disabled=true;try{const firstLoad=!status;await load();if(firstLoad||(view!=='protection'&&!content.contains(document.activeElement))||(manual&&!dirty))render();else if(view==='protection')renderActions();if(!operatorNotice)message('');}catch(error){failure(error);}finally{busy=false;refreshButton.disabled=false;if(!closed&&!sessionGone)timer=setTimeout(()=>refresh(),5000);}}
+    async function mutate(operation,success){if(mutation||closed||!checkSession())return;if(busy){message('A refresh is finishing. Please try the action again.');return;}mutation=true;operatorNotice=true;content.inert=true;content.setAttribute('aria-busy','true');clearTimeout(timer);try{await operation();await load();render();message(success);}catch(error){failure(error);}finally{mutation=false;content.inert=false;content.removeAttribute('aria-busy');if(!closed&&!sessionGone)render();if(!closed&&!sessionGone)timer=setTimeout(()=>refresh(),5000);}}
+    refreshButton.onclick=()=>{clearTimeout(timer);refresh(true);};renderTabs();refresh();
+    return ()=>{closed=true;clearTimeout(timer);unsubscribe();client.close();root.replaceChildren();};
+}

package/security/ui/main.js

@@ -0,0 +1,15 @@
+if (!app.routes?.superuserOnly || !app.store?.headerLinks || !app.pb?.send) {
+    throw new Error('Security adapter: unsupported PocketBase admin extension API');
+}
+const base = app.pb.buildURL('/_/extensions/security/');
+const stylesheet = document.createElement('link');
+stylesheet.rel = 'stylesheet';
+stylesheet.href = base + 'dashboard.css';
+document.head.append(stylesheet);
+app.routes.superuserOnly('#/security', async () => {
+    const { securityPage } = await import(base + 'dashboard.js');
+    return securityPage(app);
+});
+if (!app.store.headerLinks.some(link => link.href === '#/security')) {
+    app.store.headerLinks.push({ href: '#/security', label: 'Security', icon: 'ri-shield-check-line' });
+}

package/security/ui/model.js

@@ -0,0 +1,32 @@
+export const families = ['auth', 'reads', 'writes', 'files', 'realtime', 'other'];
+export const familyLabels = { auth: 'Authentication', reads: 'Record reads', writes: 'Record writes', files: 'Files', realtime: 'Realtime', other: 'Other / health' };
+export function rate(window) { return Number(window?.count || 0) / 10; }
+export function percent(part, total) { return total > 0 ? Math.round(100 * part / total) : 0; }
+export function filterIncidents(items, phase, family) {
+    return items.filter(i => (!phase || (phase === 'unreviewed' ? !i.acknowledged : i.phase === phase)) && (!family || i.family === family)).sort((a,b) => b.id-a.id);
+}
+export function timestamp(value) {
+    if (!value || String(value).startsWith('0001-')) return 'Not available yet';
+    const date = new Date(value);
+    return Number.isNaN(date.valueOf()) ? 'Not available' : date.toLocaleString();
+}
+export function sessionRequest(send, getSession, onExpired = () => {}) {
+    let alive = true;
+    const initial = getSession();
+    const abort = new AbortController();
+    return {
+        async request(path, options = {}) {
+            if (!alive || getSession() !== initial) throw new Error('Session changed. Reopen Security.');
+            try {
+                const result = await send('/api/security/' + path, { ...options, signal: abort.signal, requestKey: null });
+                if (!alive || getSession() !== initial) throw new Error('Session changed. Reopen Security.');
+                return result;
+            } catch (error) {
+                if (alive && error.status === 401) onExpired();
+                throw error;
+            }
+        },
+        close() { alive = false; abort.abort(); },
+        valid() { return alive && getSession() === initial; },
+    };
+}

package/security/ui/model.test.mjs

@@ -0,0 +1,25 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {sessionRequest,filterIncidents,percent,rate} from './model.js';
+test('filters retain acknowledged active incidents unless unreviewed selected',()=>{
+ const rows=[{id:1,phase:'active',family:'auth',acknowledged:true},{id:2,phase:'resolved',family:'reads',acknowledged:false}];
+ assert.deepEqual(filterIncidents(rows,'active','auth').map(i=>i.id),[1]);
+ assert.deepEqual(filterIncidents(rows,'unreviewed','').map(i=>i.id),[2]);
+ assert.equal(percent(0,0),0);assert.equal(rate({count:120}),12);
+});
+test('logout discards a pending response',async()=>{
+ let session='one',resolve;
+ const client=sessionRequest(()=>new Promise(r=>resolve=r),()=>session);
+ const pending=client.request('status');session='two';resolve({secret:'old session'});
+ await assert.rejects(pending,/Session changed/);
+});
+test('unmount aborts and rejects late responses',async()=>{
+ let resolve,signal;
+ const client=sessionRequest((_,opts)=>{signal=opts.signal;return new Promise(r=>resolve=r);},()=> 'same');
+ const pending=client.request('status');client.close();assert.equal(signal.aborted,true);resolve({});await assert.rejects(pending,/Session changed/);
+});
+test('authentication failure invokes login handling',async()=>{
+ let expired=false;
+ const client=sessionRequest(async()=>{throw Object.assign(new Error('expired'),{status:401});},()=> 'same',()=>expired=true);
+ await assert.rejects(client.request('status'));assert.equal(expired,true);
+});

package/security/ui/registration.test.mjs

@@ -0,0 +1,10 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {readFile} from 'node:fs/promises';
+import vm from 'node:vm';
+test('route is registered before extension loader returns without awaiting a dynamic import',async()=>{
+ const source=await readFile(new URL('./main.js',import.meta.url),'utf8');let registered=false;
+ const app={routes:{superuserOnly(path,handler){assert.equal(path,'#/security');assert.equal(typeof handler,'function');registered=true;}},store:{headerLinks:[]},pb:{send(){},buildURL:p=>p}};
+ vm.runInNewContext(source,{app,document:{createElement:()=>({}),head:{append(){}}}});
+ assert.equal(registered,true);assert.equal(app.store.headerLinks[0].label,'Security');
+});

package/settings/env_test.go

@@ -0,0 +1,41 @@
+package settings_test
+
+import (
+	"github.com/pocketbase/pocketbase/core"
+	_ "github.com/pocketbase/pocketbase/migrations"
+	"github.com/spink-dev/pocketbase-extension/settings"
+	"testing"
+)
+
+func TestInitialSettingsEnvironment(t *testing.T) {
+	t.Setenv("PB_SETTINGS_JSON", `{"meta":{"appName":"Environment","hideControls":false}}`)
+	app := core.NewBaseApp(core.BaseAppConfig{DataDir: t.TempDir()})
+	settings.Register(app)
+	if err := app.Bootstrap(); err != nil {
+		t.Fatal(err)
+	}
+	defer app.ResetBootstrapState()
+	if app.Settings().Meta.AppName != "Environment" {
+		t.Fatal("ignored environment")
+	}
+	app.Settings().Meta.AppName = "Dashboard"
+	if err := app.Save(app.Settings()); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PB_SETTINGS_JSON", `{"meta":{"appName":"Changed environment"}}`)
+	if err := app.ReloadSettings(); err != nil {
+		t.Fatal(err)
+	}
+	if app.Settings().Meta.AppName != "Dashboard" {
+		t.Fatal("overwrote persisted settings")
+	}
+}
+func TestInitialSettingsEnvironmentRejectsUnknown(t *testing.T) {
+	t.Setenv("PB_SETTINGS_JSON", `{"meta":{"unknownKey":"secret"}}`)
+	app := core.NewBaseApp(core.BaseAppConfig{DataDir: t.TempDir()})
+	defer app.ResetBootstrapState()
+	settings.Register(app)
+	if err := app.Bootstrap(); err == nil {
+		t.Fatal("accepted unknown settings")
+	}
+}

package/settings/openapi.json

@@ -0,0 +1,193 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Spink PocketBase extension",
+    "version": "0.1.0"
+  },
+  "components": {
+    "securitySchemes": {
+      "superuser": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "Authorization"
+      }
+    }
+  },
+  "paths": {
+    "/api/spink/settings": {
+      "get": {
+        "summary": "Read extension configuration and key availability",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "400": {
+            "description": "Invalid input"
+          },
+          "401": {
+            "description": "Authentication required"
+          },
+          "403": {
+            "description": "Insufficient permissions"
+          },
+          "409": {
+            "description": "Stale configuration revision"
+          }
+        },
+        "security": [
+          {
+            "superuser": []
+          }
+        ]
+      },
+      "put": {
+        "summary": "Save extension configuration with matching revision",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "400": {
+            "description": "Invalid input"
+          },
+          "401": {
+            "description": "Authentication required"
+          },
+          "403": {
+            "description": "Insufficient permissions"
+          },
+          "409": {
+            "description": "Stale configuration revision"
+          }
+        },
+        "security": [
+          {
+            "superuser": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "revision",
+                  "backups"
+                ],
+                "properties": {
+                  "revision": {
+                    "type": "integer"
+                  },
+                  "backups": {
+                    "type": "object",
+                    "properties": {
+                      "encrypted": {
+                        "type": "boolean"
+                      },
+                      "encryptionEnv": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  "emailLocales": {
+                    "type": "object",
+                    "description": "collection ID/name -> template kind -> lowercase locale -> subject/body"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/spink/backups/upload": {
+      "post": {
+        "summary": "Upload encrypted .zip.age backup",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "400": {
+            "description": "Invalid input"
+          },
+          "401": {
+            "description": "Authentication required"
+          },
+          "403": {
+            "description": "Insufficient permissions"
+          },
+          "409": {
+            "description": "Stale configuration revision"
+          },
+          "204": {
+            "description": "Uploaded"
+          }
+        },
+        "security": [
+          {
+            "superuser": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "file"
+                ],
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "format": "binary"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/collections/{collection}/records/{id}/duplicate": {
+      "post": {
+        "summary": "Duplicate a visible base record through stock create authorization",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "400": {
+            "description": "Invalid input"
+          },
+          "401": {
+            "description": "Authentication required"
+          },
+          "403": {
+            "description": "Insufficient permissions"
+          },
+          "409": {
+            "description": "Stale configuration revision"
+          }
+        },
+        "parameters": [
+          {
+            "name": "collection",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    }
+  }
+}