arcane-os 0.1.0-dev.5

package/runtime/arcane/modules/LocalAIReadinessController.js

@@ -0,0 +1,156 @@
+import {
+    checkLocalAIReadiness,
+    deriveLocalAIRequirements
+} from './LocalAIReadiness.js?v=4';
+
+const SLOT_NAMES=Object.freeze(['llm','stt','tts']);
+
+function availabilityFromReport(report={}){
+    const slots=report.slots||{};
+    return Object.freeze(Object.fromEntries(SLOT_NAMES.map(name=>{
+        const slot=slots[name]||{};
+        return [name,!slot.required||slot.ready===true];
+    })));
+}
+
+function selectedPreferences(source){
+    return typeof source==='function'?source():source;
+}
+
+function pendingReport(requirements){
+    return Object.freeze({
+        slots:Object.freeze(Object.fromEntries(SLOT_NAMES.map(name=>[
+            name,
+            Object.freeze({
+                ...requirements[name],
+                ready:requirements[name].required?false:null
+            })
+        ])))
+    });
+}
+
+async function waitForStatusComponent(status){
+    if(!status||status.ready){
+        return status;
+    }
+
+    await new Promise(resolve=>{
+        const timeout=globalThis.setTimeout(done,10000);
+        function done(){
+            globalThis.clearTimeout(timeout);
+            status.removeEventListener('local-ai-status-ready',done);
+            resolve();
+        }
+        status.addEventListener('local-ai-status-ready',done,{once:true});
+    });
+    return status;
+}
+
+/**
+ * Connects the shared readiness contract to a chat surface. Applications own
+ * only their preference source and navigation destinations.
+ */
+export function createLocalAIReadinessController({
+    chat,
+    status,
+    preferences,
+    profileHref=null,
+    onChange,
+    ...checkOptions
+}={}){
+    if(!chat){
+        throw new TypeError('A chat component is required.');
+    }
+
+    let active=null;
+    let latestReport=null;
+    let currentAvailability=availabilityFromReport({});
+
+    const publishAvailability=()=>{
+        if(typeof chat.setAIAvailability==='function'){
+            chat.setAIAvailability(currentAvailability);
+        }else{
+            chat.addEventListener('chat-ready',publishAvailability,{once:true});
+        }
+    };
+
+    const applyAvailability=report=>{
+        currentAvailability=availabilityFromReport(report);
+        publishAvailability();
+    };
+
+    const check=async()=>{
+        if(active){
+            return active;
+        }
+
+        active=(async()=>{
+            const preferenceTuple=selectedPreferences(preferences);
+            const requirements=deriveLocalAIRequirements(preferenceTuple);
+            const required=SLOT_NAMES.some(name=>requirements[name].required);
+
+            applyAvailability(pendingReport(requirements));
+            await waitForStatusComponent(status);
+            status?.configure?.({profileHref});
+            if(required){
+                status?.begin?.(requirements);
+            }else if(status){
+                status.hidden=true;
+            }
+
+            latestReport=await checkLocalAIReadiness({
+                ...checkOptions,
+                preferences:preferenceTuple
+            });
+            status?.present?.(latestReport);
+            applyAvailability(latestReport);
+            if(typeof onChange==='function'){
+                onChange(latestReport);
+            }
+            chat.dispatchEvent(new CustomEvent('local-ai-readiness-change',{
+                bubbles:true,
+                composed:true,
+                detail:{report:latestReport}
+            }));
+            return latestReport;
+        })().finally(()=>{
+            active=null;
+        });
+
+        return active;
+    };
+
+    const ensure=()=>{
+        if(active){
+            return active;
+        }
+        return latestReport
+            ?Promise.resolve(latestReport)
+            :check();
+    };
+
+    const retry=()=>void check();
+    status?.addEventListener('local-ai-retry',retry);
+
+    return Object.freeze({
+        check,
+        ensure,
+        destroy(){
+            status?.removeEventListener('local-ai-retry',retry);
+        },
+        get availability(){
+            return currentAvailability;
+        },
+        get report(){
+            return latestReport;
+        },
+        readyFor(name){
+            if(!SLOT_NAMES.includes(name)){
+                throw new TypeError('Local AI slot must be llm, stt, or tts.');
+            }
+            return currentAvailability[name];
+        }
+    });
+}
+
+export {availabilityFromReport};

package/runtime/arcane/modules/MD.js

@@ -0,0 +1,111 @@
+import { marked } from './Marked.min.js';
+import Is from '../../node_modules/strong-type/index.js';
+
+marked.use(
+    {
+        async: false,
+        pedantic: false,
+        gfm: true,
+        renderer: {
+            link(href, title, text) {
+                const link = marked.Renderer.prototype.link.call(this, href, title, text);
+                return link.replace("<a","<a target='_blank' ");
+            }
+        }
+    }
+);
+
+const is = new Is(false);
+
+class MD {
+    #raw='';
+    #rendered=''
+
+    constructor(raw=''){
+        this.raw=raw;
+        this.rendered=marked.parse(raw);
+        return this;
+    }
+
+    get rendered(){
+        return this.#rendered;
+    }
+
+    get safeRendered(){
+        return sanitize(this.#rendered);
+    }
+
+    set rendered(value=''){
+        return this.#rendered;
+    }
+
+    get raw(){
+        return this.#raw;
+    }
+
+    set raw(value=''){
+        if(!is.string(value)){
+            console.trace('MD.raw must be a string.');
+            return this.#raw;
+        }
+        this.#raw = value;
+        this.#rendered = marked.parse(value);
+        return this.#raw;
+    }
+
+    append(value=''){
+        if(!is.string(value)){
+            console.trace('MD.append must be a string.');
+            return this.#raw;
+        }
+        this.#raw += value;
+        this.#rendered = marked.parse(this.#raw);
+        return this.#raw;
+    }
+}
+
+function sanitize(html=''){
+    const template=document.createElement('template');
+    template.innerHTML=html;
+
+    template.content.querySelectorAll(
+        'script,style,iframe,object,embed,link,meta,base,form,input,button,textarea,select,option,svg,math'
+    ).forEach(element=>element.remove());
+
+    template.content.querySelectorAll('*').forEach(
+        function sanitizeElement(element){
+            const attributes=Array.from(element.attributes);
+
+            for(let i=0;i<attributes.length;i++){
+                const attribute=attributes[i];
+                const name=attribute.name.toLowerCase();
+
+                if(name.startsWith('on')||name==='style'||name==='srcdoc'){
+                    element.removeAttribute(attribute.name);
+                    continue;
+                }
+
+                if(!['href','src','xlink:href'].includes(name)){
+                    continue;
+                }
+
+                const value=attribute.value
+                    .replace(/[\u0000-\u001F\u007F\s]+/g,'')
+                    .toLowerCase();
+                const safeImage=name==='src'&&value.startsWith('data:image/');
+
+                if(
+                    value.startsWith('javascript:')
+                    || value.startsWith('vbscript:')
+                    || value.startsWith('data:')&&!safeImage
+                ){
+                    element.removeAttribute(attribute.name);
+                }
+            }
+        }
+    );
+
+    return template.innerHTML;
+}
+
+export default MD;

package/runtime/arcane/modules/Mail.js

@@ -0,0 +1,352 @@
+import {
+    DEFAULT_MAIL_REQUEST_TIMEOUT_MS,
+    sendMailReport,
+} from './MailTransport.mjs';
+
+let userInstance=null;
+
+async function loadOptionalMailDependencies(){
+    await import('./DBOPFS.js');
+    if(!userInstance){
+        const { default:UserEntity }=await import('../entities/User.js');
+        userInstance=new UserEntity();
+    }
+    return {
+        dbopfs:globalThis.dbopfs,
+        user:userInstance,
+    };
+}
+
+const MAX_SUBJECT_LENGTH=160;
+const MAX_MESSAGE_BYTES=25*1024*1024;
+const MAX_NATIVE_REPORT_BYTES=768*1024;
+const MAIL_TYPES=new Set(['error','report','crisis_detected']);
+const EMAIL_PATTERN=/^[a-z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+const ARCANE_APP_ID_PATTERN=/^[a-z0-9](?:[a-z0-9-]{0,62})$/;
+
+function declaredApplicationId(document=globalThis.document){
+    const value=document?.querySelector?.('meta[name="arcane-app-id"]')?.content?.trim();
+    return ARCANE_APP_ID_PATTERN.test(value||'') ? value:'';
+}
+
+function declaredMailBaseDomain(document=globalThis.document){
+    return normalizeBaseDomain(
+        document?.querySelector?.('meta[name="arcane-mail-base-domain"]')?.content,
+    );
+}
+
+function normalizeBaseDomain(value){
+    const domain=String(value||'').trim().toLowerCase();
+    if(!domain||domain.length>253
+        || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(domain)){
+        return '';
+    }
+    return domain;
+}
+
+function hostedBaseDomain(hostname,configuredBaseDomain=''){
+    const configured=normalizeBaseDomain(configuredBaseDomain);
+    return configured&&(hostname===configured||hostname.endsWith(`.${configured}`)) ? configured:'';
+}
+
+function defaultMailEndpoint(location=globalThis.location,baseDomain=''){
+    if(!location||!['http:','https:'].includes(location.protocol)){
+        return '';
+    }
+    const hostname=String(location.hostname||'').toLowerCase();
+    const loopback=['localhost','127.0.0.1','::1','[::1]'].includes(hostname);
+    if(loopback&&location.protocol==='http:'&&String(location.port||'')!=='8025'){
+        const authority=hostname==='::1' ? '[::1]':hostname;
+        return `http://${authority}:8025/v1/mail`;
+    }
+    if(loopback){
+        return new URL('/v1/mail',location.origin).href;
+    }
+    const root=hostedBaseDomain(hostname,baseDomain);
+    if(!root){
+        return '';
+    }
+    return `https://mail.${root}/v1/mail`;
+}
+
+export function resolveMailConfig(
+    config=globalThis.arcane?.config?.mail||{},
+    {document=globalThis.document,location=globalThis.location}={}
+){
+    const supplied=config&&typeof config==='object'&&!Array.isArray(config)?config:{};
+    const appName=typeof supplied.appName==='string'&&supplied.appName.trim()
+        ? supplied.appName.trim()
+        : declaredApplicationId(document);
+    return Object.freeze({
+        appName:ARCANE_APP_ID_PATTERN.test(appName) ? appName:'',
+        appKey:typeof supplied.appKey==='string' ? supplied.appKey:'',
+        endpoint:typeof supplied.endpoint==='string'&&supplied.endpoint.trim()
+            ? supplied.endpoint.trim()
+            : defaultMailEndpoint(location,supplied.baseDomain||declaredMailBaseDomain(document)),
+        requestTimeout:Number.isFinite(supplied.requestTimeout)
+            ? supplied.requestTimeout
+            : DEFAULT_MAIL_REQUEST_TIMEOUT_MS,
+    });
+}
+
+function escapeHtml(value){
+    return String(value)
+        .replaceAll('&','&')
+        .replaceAll('<','&lt;')
+        .replaceAll('>','&gt;')
+        .replaceAll('"','&quot;')
+        .replaceAll("'",'&#39;');
+}
+
+function utf8ByteLength(value){
+    return new TextEncoder().encode(value).byteLength;
+}
+
+function clonePayload(value){
+    if(typeof globalThis.structuredClone==='function'){
+        return globalThis.structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+
+function serializePayload(value){
+    try{
+        return JSON.stringify(value,null,2);
+    }catch{
+        return '[The structured payload could not be serialized.]';
+    }
+}
+
+function assertMessageSize(report){
+    const messageBytes=['text','html'].reduce(
+        (total,key)=>total+utf8ByteLength(report[key]||''),
+        0
+    );
+    if(messageBytes>MAX_MESSAGE_BYTES){
+        throw new Error('Generated report email content exceeds the 25 MiB limit');
+    }
+}
+
+function assertNativeReportSize(report){
+    const serialized=JSON.stringify(report);
+    if(utf8ByteLength(serialized)>MAX_NATIVE_REPORT_BYTES){
+        throw new RangeError('Native Arcane mail reports cannot exceed 786,432 serialized bytes');
+    }
+}
+
+function createReportKey(subject){
+    const safeSubject=subject
+        .normalize('NFKD')
+        .replace(/[^a-z0-9_-]+/gi,'_')
+        .replace(/^_+|_+$/g,'')
+        .slice(0,48)||'notification';
+    let nonce;
+    if(typeof globalThis.crypto?.randomUUID==='function'){
+        nonce=globalThis.crypto.randomUUID();
+    }else if(typeof globalThis.crypto?.getRandomValues==='function'){
+        const bytes=globalThis.crypto.getRandomValues(new Uint8Array(16));
+        nonce=[...bytes].map(value=>value.toString(16).padStart(2,'0')).join('');
+    }else{
+        nonce=Math.random().toString(36).slice(2).padEnd(16,'0').slice(0,16);
+    }
+    return `${Date.now()}-${nonce}-email-${safeSubject}.json`;
+}
+
+function normalizeRecipients(values){
+    if(!Array.isArray(values)){
+        throw new TypeError('Mail recipients must be an array');
+    }
+    if(values.length>50){
+        throw new TypeError('Mail supports no more than 50 recipients');
+    }
+
+    const recipients=[];
+    for(const value of values){
+        if(!value){
+            continue;
+        }
+
+        if(typeof value!=='string'){
+            throw new TypeError('Every mail recipient must be an email address');
+        }
+
+        const address=value.trim().toLowerCase();
+        if(address.length>254||!EMAIL_PATTERN.test(address)){
+            throw new TypeError('Mail contains an invalid recipient address');
+        }
+
+        if(!recipients.includes(address)){
+            recipients.push(address);
+        }
+    }
+
+    return recipients;
+}
+
+class Mail {
+    constructor(config=globalThis.arcane?.config?.mail||{}) {
+        if(globalThis.window?.mail){
+            return globalThis.window.mail;
+        }
+
+        const resolved=resolveMailConfig(config);
+        this.appName=resolved.appName;
+        this.appKey=resolved.appKey;
+        this.endpoint=resolved.endpoint;
+        this.requestTimeout=resolved.requestTimeout;
+    }
+
+    #assertConfigured(){
+        if(!this.appName||(!this.endpoint&&typeof globalThis.Arcane?.mail?.send!=='function')){
+            throw new Error('Mail transport is not configured');
+        }
+    }
+
+    async #deliver(report,reportKey){
+        if(typeof globalThis.Arcane?.mail?.send==='function'){
+            assertNativeReportSize(report);
+            return globalThis.Arcane.mail.send({report,reportKey});
+        }
+        return sendMailReport({
+            appKey:this.appKey,
+            appName:this.appName,
+            endpoint:this.endpoint,
+            report,
+            reportKey,
+            requestTimeout:this.requestTimeout,
+        });
+    }
+
+    async send(to=[], subject='', payload={}, messageStyle='', messageType='') {
+        const normalizedSubject=typeof subject==='string' ? subject.trim():'';
+        if(!normalizedSubject||normalizedSubject.length>MAX_SUBJECT_LENGTH||/[\u0000-\u001f\u007f]/.test(normalizedSubject)){
+            throw new TypeError(`Mail subject must contain 1-${MAX_SUBJECT_LENGTH} characters without line breaks`);
+        }
+        if(!payload||typeof payload!=='object'||Array.isArray(payload)){
+            throw new TypeError('Mail payload must be an object');
+        }
+        if(typeof messageStyle!=='string'){
+            throw new TypeError('Mail message style must be a string');
+        }
+        if(!Array.isArray(to)){
+            throw new TypeError('Mail recipients must be an array');
+        }
+        if(typeof messageType!=='string'||!MAIL_TYPES.has(messageType)){
+            throw new TypeError('Mail type must be error, report, or crisis_detected');
+        }
+
+        this.#assertConfigured();
+
+        const recipients=normalizeRecipients(to);
+        if(messageType!=='error'&&recipients.length===0){
+            throw new TypeError('Report and crisis mail require at least one recipient');
+        }
+
+        const reportKey=createReportKey(normalizedSubject);
+        const reportPayload={
+            ...clonePayload(payload),
+            source_at:new Date().toISOString(),
+            source_path:globalThis.location?.pathname||'',
+            subject:normalizedSubject,
+            type:messageType,
+        };
+
+        if(messageType==='error'){
+            reportPayload.report={
+                subject:normalizedSubject,
+                text:`${this.appName} application error\n\n${serializePayload(reportPayload)}`,
+                to:recipients,
+                type:messageType,
+            };
+            assertMessageSize(reportPayload.report);
+
+            const delivery=await this.#deliver(reportPayload.report,reportKey);
+            return { ...delivery,reportKey };
+        }
+
+        let reportStorage=null;
+        let profile={ email:'',language:'',phone:'',username:'' };
+        try{
+            const dependencies=await loadOptionalMailDependencies();
+            reportStorage=dependencies.dbopfs;
+            try{
+                await dependencies.user.load();
+            }catch(error){
+                console.warn('Unable to load the user profile for mail; continuing with available values.',error);
+            }
+            profile={
+                email:dependencies.user.email,
+                language:dependencies.user.language,
+                phone:dependencies.user.phone,
+                username:dependencies.user.username,
+            };
+        }catch(error){
+            console.warn('Optional mail formatting dependencies are unavailable; using a deterministic fallback.',error);
+        }
+
+        const wantsHtml=/\bhtml\b/i.test(messageStyle);
+        Object.assign(reportPayload,{
+            email:profile.email,
+            language:profile.language,
+            phone:profile.phone,
+            source_user:profile.username || 'username not specified',
+        });
+
+        // Email formatting stays local and deterministic. The supplied style
+        // is presentation intent only; it is never sent to an AI provider and
+        // untrusted report values are escaped before entering HTML.
+        const serialized=serializePayload(reportPayload);
+        const generatedMessage=wantsHtml
+            ? `<pre>${escapeHtml(serialized)}</pre>`
+            : serialized;
+
+        const sourceUser=String(reportPayload.source_user)
+            .replace(/[\u0000-\u001f\u007f]/g,' ')
+            .trim()
+            .slice(0,80);
+        const subjectSuffix=sourceUser ? ` - ${sourceUser}`:'';
+        const deliverySubject=normalizedSubject.length+subjectSuffix.length<=MAX_SUBJECT_LENGTH
+            ? `${normalizedSubject}${subjectSuffix}`
+            : normalizedSubject;
+
+        reportPayload.report = {
+            subject:deliverySubject,
+            to:recipients,
+            type:messageType,
+        };
+        if(wantsHtml){
+            reportPayload.report.html=`${generatedMessage}
+<hr>
+<p>Phone: ${escapeHtml(profile.phone || 'not provided')}<br>Email: ${escapeHtml(profile.email || 'not provided')}</p>`;
+        }else{
+            reportPayload.report.text=`${generatedMessage}
+
+Phone: ${profile.phone || 'not provided'}
+Email: ${profile.email || 'not provided'}`;
+        }
+
+        assertMessageSize(reportPayload.report);
+
+        try{
+            if(!reportStorage?.set){
+                throw new Error('Report storage is unavailable');
+            }
+            await reportStorage.set('reports',reportKey,reportPayload);
+        }catch(error){
+            console.warn('Unable to store the generated mail report; continuing with delivery.',error);
+        }
+
+        const delivery=await this.#deliver(reportPayload.report,reportKey);
+        
+        return {
+            ...delivery,
+            reportKey,
+        };
+    }
+}
+
+if(globalThis.window&&!globalThis.window.mail){
+    globalThis.window.mail=new Mail();
+}
+
+export default Mail;