arcane-os 0.1.0-dev.5

package/runtime/arcane/modules/AppDataScope.js

@@ -0,0 +1,245 @@
+const APPLICATION_ID_PATTERN=/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const APPLICATION_ID_MAX_LENGTH=64;
+const APP_DATA_DIRECTORY='apps';
+const APP_LOCAL_STORAGE_PREFIX='arcane.apps.';
+
+function scopeError(code,message){
+    const error=new Error(message);
+    error.code=code;
+    return error;
+}
+
+/**
+ * Validates the canonical application identifier used by Arcane packages,
+ * the native host, and application-owned data folders.
+ *
+ * @param {*} value
+ * @param {string} label
+ * @returns {string}
+ */
+export function canonicalApplicationId(value,label='applicationId'){
+    if(typeof value!=='string'
+        ||value.length<1
+        ||value.length>APPLICATION_ID_MAX_LENGTH
+        ||!APPLICATION_ID_PATTERN.test(value)){
+        throw scopeError(
+            'APP_DATA_SCOPE_INVALID',
+            `${label} must be a canonical Arcane application identifier.`
+        );
+    }
+
+    return value;
+}
+
+/**
+ * Reads the immutable application declaration from a document. Application
+ * pages declare this before storage modules run so standalone browser builds
+ * do not depend on their mount path for identity.
+ *
+ * @param {Document|Object|null} documentObject
+ * @returns {string|null}
+ */
+export function declaredApplicationId(documentObject=globalThis.document){
+    const metaValue=documentObject
+        ?.querySelector?.('meta[name="arcane-app-id"]')
+        ?.getAttribute?.('content');
+    const rootValue=documentObject?.documentElement?.dataset?.arcaneAppId;
+    const declarations=[metaValue,rootValue]
+        .filter(value=>value!==null&&value!==undefined&&value!=='')
+        .map((value,index)=>canonicalApplicationId(
+            value,
+            index===0?'arcane-app-id metadata':'document application id'
+        ));
+
+    if(new Set(declarations).size>1){
+        throw scopeError(
+            'APP_DATA_SCOPE_MISMATCH',
+            'The document contains conflicting Arcane application identities.'
+        );
+    }
+
+    return declarations[0]||null;
+}
+
+/**
+ * Resolves the synchronous browser declaration used by storage mechanisms
+ * such as localStorage. Native-capable asynchronous callers must use
+ * resolveApplicationId so the host-bound identity remains authoritative.
+ *
+ * @param {Object} options
+ * @param {string|null} options.applicationId
+ * @param {Document|Object|null} options.documentObject
+ * @returns {string}
+ */
+export function resolveBrowserApplicationId({
+    applicationId=null,
+    documentObject=globalThis.document
+}={}){
+    const explicit=applicationId===null||applicationId===undefined||applicationId===''
+        ?null
+        :canonicalApplicationId(applicationId);
+    const declared=declaredApplicationId(documentObject);
+
+    if(explicit&&declared&&explicit!==declared){
+        throw scopeError(
+            'APP_DATA_SCOPE_MISMATCH',
+            'The configured and declared Arcane application identities do not match.'
+        );
+    }
+
+    if(explicit||declared){
+        return explicit||declared;
+    }
+
+    throw scopeError(
+        'APP_DATA_SCOPE_REQUIRED',
+        'Arcane application data cannot open without a declared application identity.'
+    );
+}
+
+/**
+ * Resolves a logical local-storage key beneath the current browser app scope.
+ * Callers retain their domain namespace while the shared mechanism supplies
+ * the canonical `arcane.apps.<id>:` ownership prefix.
+ *
+ * @param {*} logicalKey
+ * @param {Object} options
+ * @returns {string}
+ */
+export function resolveApplicationLocalStorageKey(logicalKey='',options={}){
+    const applicationId=resolveBrowserApplicationId(options);
+    return `${APP_LOCAL_STORAGE_PREFIX}${applicationId}:${String(logicalKey)}`;
+}
+
+async function nativeApplicationId(arcane=globalThis.Arcane){
+    if(typeof arcane?.app?.current!=='function'){
+        return null;
+    }
+
+    const descriptor=await arcane.app.current();
+
+    if(!descriptor||typeof descriptor!=='object'){
+        throw scopeError(
+            'APP_DATA_SCOPE_INVALID',
+            'Arcane returned an invalid bound application descriptor.'
+        );
+    }
+
+    return canonicalApplicationId(
+        descriptor.id,
+        'bound application id'
+    );
+}
+
+/**
+ * Resolves one application identity for persistent data. The native host is
+ * authoritative when present. Browser-only applications must declare their
+ * package id in `meta[name="arcane-app-id"]` (or the equivalent root data
+ * attribute). A mismatch fails closed before a data directory is opened.
+ *
+ * @param {Object} options
+ * @param {string|null} options.applicationId Explicit identity for adapters
+ *   and synthetic tests. Application pages should use document metadata.
+ * @param {Document|Object|null} options.documentObject
+ * @param {Object|null} options.arcane
+ * @returns {Promise<string>}
+ */
+export async function resolveApplicationId({
+    applicationId=null,
+    documentObject=globalThis.document,
+    arcane=globalThis.Arcane
+}={}){
+    let browserIdentity=null;
+    try{
+        browserIdentity=resolveBrowserApplicationId({
+            applicationId,
+            documentObject
+        });
+    }catch(error){
+        if(error?.code!=='APP_DATA_SCOPE_REQUIRED'){
+            throw error;
+        }
+    }
+    const nativeIdentity=await nativeApplicationId(arcane);
+
+    if(nativeIdentity&&browserIdentity&&nativeIdentity!==browserIdentity){
+        throw scopeError(
+            'APP_DATA_SCOPE_MISMATCH',
+            'The document identity does not match the application bound by Arcane.'
+        );
+    }
+
+    if(nativeIdentity||browserIdentity){
+        return nativeIdentity||browserIdentity;
+    }
+
+    throw scopeError(
+        'APP_DATA_SCOPE_REQUIRED',
+        'Arcane application data cannot open without a bound application identity.'
+    );
+}
+
+/**
+ * Opens `<OPFS root>/apps/<application-id>` and returns only that app-owned
+ * directory. This is an organizational boundary for browser-only same-origin
+ * code; the native host additionally supplies a separate WebView profile and
+ * authoritative application identity.
+ *
+ * @param {Object} options
+ * @param {StorageManager|Object} options.storage
+ * @param {string|null} options.applicationId
+ * @param {Document|Object|null} options.documentObject
+ * @param {Object|null} options.arcane
+ * @param {boolean} options.create
+ * @returns {Promise<{applicationId:string,directory:FileSystemDirectoryHandle|Object,path:string}>}
+ */
+export async function openApplicationDataDirectory({
+    storage=globalThis.navigator?.storage,
+    applicationId=null,
+    documentObject=globalThis.document,
+    arcane=globalThis.Arcane,
+    create=true
+}={}){
+    if(!storage||typeof storage.getDirectory!=='function'){
+        throw scopeError(
+            'APP_DATA_STORAGE_UNAVAILABLE',
+            'Origin Private File System storage is unavailable in this browser.'
+        );
+    }
+
+    const id=await resolveApplicationId({
+        applicationId,
+        documentObject,
+        arcane
+    });
+    const root=await storage.getDirectory();
+
+    if(!root||typeof root.getDirectoryHandle!=='function'){
+        throw scopeError(
+            'APP_DATA_STORAGE_UNAVAILABLE',
+            'Arcane could not open the Origin Private File System root.'
+        );
+    }
+
+    const applications=await root.getDirectoryHandle(
+        APP_DATA_DIRECTORY,
+        {create:Boolean(create)}
+    );
+    const directory=await applications.getDirectoryHandle(
+        id,
+        {create:Boolean(create)}
+    );
+
+    return {
+        applicationId:id,
+        directory,
+        path:`${APP_DATA_DIRECTORY}/${id}`
+    };
+}
+
+export {
+    APPLICATION_ID_MAX_LENGTH,
+    APPLICATION_ID_PATTERN,
+    APP_DATA_DIRECTORY,
+    APP_LOCAL_STORAGE_PREFIX
+};

package/runtime/arcane/modules/AppearancePreferences.js

@@ -0,0 +1,28 @@
+import PreferenceStore from './PreferenceStore.js';
+
+export const appearancePreferenceSchema=Object.freeze([
+    {key:'appearance.colorScheme',type:'select',label:'Color scheme',description:'Use the device preference or choose a consistent light or dark appearance.',defaultValue:'system',options:[{label:'Use device setting',value:'system'},{label:'Light',value:'light'},{label:'Dark',value:'dark'}]},
+    {key:'appearance.density',type:'select',label:'Layout density',description:'Choose comfortable spacing or fit more information on screen.',defaultValue:'comfortable',options:[{label:'Comfortable',value:'comfortable'},{label:'Compact',value:'compact'}]},
+    {key:'accessibility.reduceMotion',type:'boolean',label:'Reduce motion',description:'Limit non-essential animation and transitions.',defaultValue:false},
+    {key:'accessibility.largeText',type:'boolean',label:'Larger text',description:'Increase the base text size in compatible Arcane applications.',defaultValue:false}
+]);
+
+export function createAppearancePreferenceStore(options={}){
+    return new PreferenceStore({namespace:'arcane',schema:appearancePreferenceSchema,...options});
+}
+
+export function applyAppearancePreferences(values={},root=document.documentElement){
+    const scheme=values['appearance.colorScheme'];
+    if(scheme==='light'||scheme==='dark') root.dataset.colorScheme=scheme; else root.removeAttribute('data-color-scheme');
+    root.dataset.density=values['appearance.density']||'comfortable';
+    root.dataset.reduceMotion=String(Boolean(values['accessibility.reduceMotion']));
+    root.style.fontSize=values['accessibility.largeText']?'18px':'';
+    return values;
+}
+
+export async function loadAndApplyAppearancePreferences(options={}){
+    const store=options.store||createAppearancePreferenceStore(options);
+    const values=await store.load();
+    applyAppearancePreferences(values,options.root||document.documentElement);
+    return {store,values};
+}

package/runtime/arcane/modules/ArcaneCommunicationBridge.js

@@ -0,0 +1,22 @@
+import CommunicationMessage from '../entities/CommunicationMessage.js';
+import CommunicationThread from '../entities/CommunicationThread.js';
+
+function cleanEndpoint(value){const url=new URL(String(value||'http://127.0.0.1:8020'));if(!['http:','https:'].includes(url.protocol)) throw new TypeError('Bridge URL must use HTTP or HTTPS.');return url.href.replace(/\/$/,'');}
+
+export default class ArcaneCommunicationBridge{
+    constructor({id,label,channels,endpoint='http://127.0.0.1:8020',fetchImpl=globalThis.fetch}={}){
+        this.id=String(id||'arcane-bridge');this.label=String(label||'Arcane communications bridge');this.channels=Array.from(channels||['other']);this.endpoint=cleanEndpoint(endpoint);this.fetchImpl=fetchImpl;
+    }
+    async request(path,options={}){
+        if(typeof this.fetchImpl!=='function') throw new Error('Network access is unavailable.');
+        const response=await this.fetchImpl(`${this.endpoint}${path}`,{...options,headers:{Accept:'application/json',...(options.body?{'Content-Type':'application/json'}:{}),...options.headers}});
+        const text=await response.text();let body={};if(text){try{body=JSON.parse(text);}catch{throw new Error('The communications bridge returned invalid JSON.');}}
+        if(!response.ok) throw new Error(body.error||`Communications bridge request failed (${response.status}).`);
+        return body;
+    }
+    async listThreads(){const body=await this.request(`/v1/providers/${encodeURIComponent(this.id)}/threads`);return Array.from(body.threads||[],value=>new CommunicationThread({...value,providerId:this.id}));}
+    async getMessages(threadId){const body=await this.request(`/v1/providers/${encodeURIComponent(this.id)}/threads/${encodeURIComponent(threadId)}/messages`);return Array.from(body.messages||[],value=>new CommunicationMessage({...value,threadId,providerId:this.id}));}
+    async send(input={}){const body=await this.request(`/v1/providers/${encodeURIComponent(this.id)}/messages`,{method:'POST',body:JSON.stringify(input)});return new CommunicationMessage({...body.message,providerId:this.id,threadId:body.message?.threadId||input.threadId,direction:'outbound'});}
+    async connect(){return this.request(`/v1/providers/${encodeURIComponent(this.id)}/connect`,{method:'POST'});}
+    async disconnect(){return this.request(`/v1/providers/${encodeURIComponent(this.id)}/disconnect`,{method:'POST'});}
+}

package/runtime/arcane/modules/ArcaneNavigationPolicy.js

@@ -0,0 +1,135 @@
+import * as ArcaneNetworkPolicy from './ArcaneNetworkPolicy.js?v=3';
+
+function boundedText(value,fallback,maximum=500){
+    const text=typeof value==='string'?value.trim():'';
+    if(!text)return fallback;
+    return text.replace(/[\u0000-\u001f\u007f]/g,' ').slice(0,maximum);
+}
+
+function decisionId(){
+    if(typeof globalThis.crypto?.randomUUID==='function')return globalThis.crypto.randomUUID();
+    return `navigation-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,10)}`;
+}
+
+function destinationContext(value){
+    const url=new URL(String(value));
+    if(!['http:','https:'].includes(url.protocol))throw new TypeError('Arcane navigation policy accepts only HTTP or HTTPS destinations.');
+    const defaultPort=url.protocol==='https:'?443:80;
+    const hostname=url.hostname;
+    const ipLiteral=isIpLiteralHostname(hostname);
+    return Object.freeze({
+        url:url.href,
+        hostname,
+        canonicalHostname:ipLiteral?hostname.replace(/^\[|\]$/g,''):ArcaneNetworkPolicy.canonicalNetworkHostname(hostname),
+        ipLiteral,
+        protocol:'tcp',
+        remotePort:url.port?Number(url.port):defaultPort
+    });
+}
+
+function isIpLiteralHostname(hostname){
+    const value=String(hostname||'').replace(/^\[|\]$/g,'');
+    if(value.includes(':'))return /^[0-9a-f:.]+$/i.test(value);
+    const parts=value.split('.');
+    return parts.length===4&&parts.every(function validIpv4Part(part){
+        return /^(?:0|[1-9]\d{0,2})$/.test(part)&&Number(part)<=255;
+    });
+}
+
+function blockedDecision(rule,target,policyGeneration,ruleType){
+    return Object.freeze({
+        blocked:true,
+        decisionId:decisionId(),
+        decidedAt:new Date().toISOString(),
+        policyGeneration,
+        ruleId:boundedText(rule?.id,'unknown-rule',80),
+        ruleType,
+        target:target.url,
+        matchedValue:ruleType==='domain'?boundedText(rule?.domain,target.hostname,253):boundedText(rule?.cidr,target.hostname,160),
+        reason:Object.freeze({
+            code:boundedText(rule?.reason?.code,'global-deny',80),
+            title:boundedText(rule?.reason?.title,'Blocked by the global deny policy',120),
+            description:boundedText(rule?.reason?.description,'Arcane stopped this navigation before sending a request.')
+        }),
+        source:Object.freeze({
+            id:boundedText(rule?.source?.id,'arcane-policy',80),
+            label:boundedText(rule?.source?.label,'Arcane global policy',120),
+            reference:boundedText(rule?.source?.reference,'',500)||null
+        })
+    });
+}
+
+function unavailableDecision(target,error){
+    return Object.freeze({
+        blocked:true,
+        decisionId:decisionId(),
+        decidedAt:new Date().toISOString(),
+        policyGeneration:null,
+        ruleId:'policy-unavailable',
+        ruleType:'policy',
+        target:target.url,
+        matchedValue:target.hostname,
+        reason:Object.freeze({
+            code:'policy-unavailable',
+            title:'Navigation paused because policy is unavailable',
+            description:'Arcane could not verify the current global deny policy, so it did not send this request.'
+        }),
+        source:Object.freeze({
+            id:'arcane-runtime',
+            label:'Arcane policy safety boundary',
+            reference:boundedText(error?.code||'','',120)||null
+        })
+    });
+}
+
+function requireNetworkMatcher(networkMatcher){
+    if(typeof networkMatcher==='function')return networkMatcher;
+    const error=new Error('Arcane cannot evaluate literal-IP navigation because the canonical network matcher is unavailable.');
+    error.code='ARCANE_NETWORK_POLICY_MATCHER_UNAVAILABLE';
+    throw error;
+}
+
+export function createArcaneNavigationGuard({
+    loadPolicy=ArcaneNetworkPolicy.loadArcaneNetworkPolicy,
+    onDecision=null,
+    networkMatcher=ArcaneNetworkPolicy.findDeniedNetworkRule
+}={}){
+    return async function guardArcaneNavigation(value,context={}){
+        const target=destinationContext(value);
+        let decision;
+        try{
+            if(!target.ipLiteral&&(!target.canonicalHostname||target.canonicalHostname!==target.hostname)){
+                const error=new TypeError('Arcane navigation policy requires a canonical hostname without a trailing root dot.');
+                error.code='ARCANE_NETWORK_POLICY_HOSTNAME_NONCANONICAL';
+                throw error;
+            }
+            const policy=await loadPolicy();
+            const domainRule=ArcaneNetworkPolicy.findDeniedDomainRule(policy,target.canonicalHostname);
+            let networkRule=null;
+            if(!domainRule&&target.ipLiteral){
+                const findDeniedNetworkRule=requireNetworkMatcher(networkMatcher);
+                networkRule=findDeniedNetworkRule(policy,target.canonicalHostname,{
+                    protocol:target.protocol,
+                    remotePort:target.remotePort
+                });
+            }
+            decision=domainRule
+                ?blockedDecision(domainRule,target,policy.generation,'domain')
+                :networkRule
+                    ?blockedDecision(networkRule,target,policy.generation,'network')
+                    :Object.freeze({
+                        blocked:false,
+                        decisionId:decisionId(),
+                        decidedAt:new Date().toISOString(),
+                        policyGeneration:policy.generation,
+                        target:target.url
+                    });
+        }catch(error){
+            decision=unavailableDecision(target,error);
+        }
+        if(typeof onDecision==='function'){
+            await onDecision(decision,Object.freeze({intent:boundedText(context.intent,'embedded',32)}));
+        }
+        return decision;
+    };
+}