arcane-os 0.2.2 → 0.3.0

package/src/mail.mjs

@@ -0,0 +1,261 @@
+import {ArcaneError,ERROR_CODES,throwIfAborted} from './errors.mjs';
+import {
+    deleteMailCredential,
+    getMailCredentialStatus,
+    readMailCredential,
+    setMailCredential
+} from './mail-credentials.mjs';
+import {sendResendMail,startResendMailServer} from './mail-server.mjs';
+
+export const MAIL_COMMAND_ACTIONS=Object.freeze([
+    'key-set',
+    'key-status',
+    'key-delete',
+    'send',
+    'serve'
+]);
+
+const ACTION_SET=new Set(MAIL_COMMAND_ACTIONS);
+
+function usage(message){
+    throw new ArcaneError(ERROR_CODES.usage,message);
+}
+
+function validateOptions(options){
+    if(!options||typeof options!=='object'||Array.isArray(options)){
+        usage('Mail command options must be an object.');
+    }
+    if(typeof options.action!=='string'||!ACTION_SET.has(options.action)){
+        usage(`Mail action must be one of: ${MAIL_COMMAND_ACTIONS.join(', ')}.`);
+    }
+    return options;
+}
+
+function dependency(options,name,fallback){
+    const value=options[name]??fallback;
+    if(typeof value!=='function'){
+        usage(`${name} must be a function when supplied.`);
+    }
+    return value;
+}
+
+function recipientList(value,label){
+    const entries=Array.isArray(value)
+        ? value
+        : typeof value==='string'
+            ? value.split(',')
+            : null;
+    if(!entries||entries.length===0||entries.length>50){
+        usage(`${label} must contain one to 50 comma-separated email addresses.`);
+    }
+    const result=entries.map(function normalizeMailRecipient(entry){
+        if(typeof entry!=='string'||!entry.trim()){
+            usage(`${label} contains an empty email address.`);
+        }
+        return entry.trim();
+    });
+    if(new Set(result.map(function lowercaseRecipient(entry){
+        return entry.toLowerCase();
+    })).size!==result.length){
+        usage(`${label} must not contain duplicate email addresses.`);
+    }
+    return result;
+}
+
+function originList(value){
+    const entries=Array.isArray(value)?value:[value];
+    if(entries.length===0||entries.some(function invalidOrigin(entry){
+        return typeof entry!=='string'||!entry.trim();
+    })){
+        usage('Mail serve requires at least one exact allowed origin.');
+    }
+    return entries.map(function normalizeAllowedOrigin(entry){return entry.trim();});
+}
+
+function credentialOptions(options){
+    return {
+        profile:options.profile,
+        platform:options.platform,
+        systemRoot:options.systemRoot,
+        temporaryDirectory:options.temporaryDirectory,
+        spawnImpl:options.spawnImpl,
+        runner:options.credentialRunner,
+        signal:options.signal,
+        timeoutMs:options.credentialTimeoutMs
+    };
+}
+
+async function setCredential(options){
+    const readSecret=dependency(options,'readSecret',null);
+    const store=dependency(options,'setCredential',setMailCredential);
+    throwIfAborted(options.signal);
+    let secret='';
+    try{
+        secret=await readSecret();
+        throwIfAborted(options.signal);
+        return await store({...credentialOptions(options),secret});
+    }finally{
+        secret='';
+    }
+}
+
+async function credentialStatus(options){
+    const status=dependency(options,'getCredentialStatus',getMailCredentialStatus);
+    throwIfAborted(options.signal);
+    return status(credentialOptions(options));
+}
+
+async function deleteCredential(options){
+    const remove=dependency(options,'deleteCredential',deleteMailCredential);
+    throwIfAborted(options.signal);
+    return remove(credentialOptions(options));
+}
+
+function safeSendFailure(result){
+    return Object.freeze({
+        provider:'resend',
+        status:result.status,
+        classification:result.classification,
+        requestId:result.requestId,
+        providerStatus:result.providerStatus,
+        recipientCount:result.recipientCount,
+        retryable:result.retryable===true,
+        uncertain:result.uncertain===true,
+        ...(typeof result.code==='string'?{code:result.code}:{}),
+        ...(Number.isSafeInteger(result.retryAfterMs)&&result.retryAfterMs>0
+            ?{retryAfterMs:result.retryAfterMs}
+            :{})
+    });
+}
+
+async function sendMail(options){
+    const readReport=dependency(options,'readReport',null);
+    const readCredential=dependency(options,'readCredential',readMailCredential);
+    const send=dependency(options,'sendMail',sendResendMail);
+    throwIfAborted(options.signal);
+    const report=await readReport();
+    throwIfAborted(options.signal);
+    let apiKey=await readCredential(credentialOptions(options));
+    if(apiKey===null){
+        throw new ArcaneError(
+            ERROR_CODES.prerequisiteMissing,
+            `No Resend credential is configured for profile ${String(options.profile)}.`
+        );
+    }
+    if(typeof apiKey!=='string'||!apiKey){
+        throw new ArcaneError(
+            ERROR_CODES.operationFailed,
+            'The configured Resend credential could not be read.'
+        );
+    }
+    try{
+        throwIfAborted(options.signal);
+        const result=await send({
+            apiKey,
+            appId:'arcane-cli',
+            fetchImpl:options.fetchImpl,
+            from:options.from,
+            maxProviderResponseBytes:options.maxProviderResponseBytes,
+            maxRequestBytes:options.maxRequestBytes,
+            onEvent:options.onEvent,
+            providerTimeoutMs:options.requestTimeout,
+            report,
+            reportKey:options.reportKey,
+            requestIdFactory:options.requestIdFactory,
+            retryableDelayMs:options.retryableDelayMs,
+            signal:options.signal
+        });
+        if(result?.classification==='accepted'&&result.status==='accepted'){
+            return result;
+        }
+        const details=safeSendFailure(result||{});
+        throw new ArcaneError(
+            ERROR_CODES.operationFailed,
+            `Resend did not authoritatively accept the mail request (${details.classification||'unknown'}).`,
+            {details}
+        );
+    }finally{
+        apiKey='';
+    }
+}
+
+async function serveMail(options){
+    const readCredential=dependency(options,'readCredential',readMailCredential);
+    const readAppKey=dependency(options,'readAppKey',null);
+    const startServer=dependency(options,'startServer',startResendMailServer);
+    throwIfAborted(options.signal);
+    let apiKey=await readCredential(credentialOptions(options));
+    if(apiKey===null){
+        throw new ArcaneError(
+            ERROR_CODES.prerequisiteMissing,
+            `No Resend credential is configured for profile ${String(options.profile)}.`
+        );
+    }
+    if(typeof apiKey!=='string'||!apiKey){
+        throw new ArcaneError(
+            ERROR_CODES.operationFailed,
+            'The configured Resend credential could not be read.'
+        );
+    }
+    let appKey='';
+    try{
+        throwIfAborted(options.signal);
+        appKey=await readAppKey();
+        if(typeof appKey!=='string'||!appKey){
+            throw new ArcaneError(
+                ERROR_CODES.operationFailed,
+                'The local Mail gateway app key could not be read.'
+            );
+        }
+        throwIfAborted(options.signal);
+        const recipientAllowlist=recipientList(options.allowTo,'allowTo');
+        const errorRecipients=options.errorTo===undefined
+            ? recipientAllowlist
+            : recipientList(options.errorTo,'errorTo');
+        return await startServer({
+            apiKey,
+            appKey,
+            appId:options.appId,
+            allowedOrigins:originList(options.origin),
+            bodyQueueTimeoutMs:options.bodyQueueTimeoutMs,
+            bodyTimeoutMs:options.bodyTimeoutMs,
+            errorRecipients,
+            fetchImpl:options.fetchImpl,
+            from:options.from,
+            host:options.host,
+            maxConcurrentBodyReads:options.maxConcurrentBodyReads,
+            maxConcurrentSends:options.maxConcurrentSends,
+            maxMessageBytes:options.maxMessageBytes,
+            maxProviderResponseBytes:options.maxProviderResponseBytes,
+            maxQueuedBodyReads:options.maxQueuedBodyReads,
+            maxQueuedSends:options.maxQueuedSends,
+            maxQueuedMessageBytes:options.maxQueuedMessageBytes,
+            maxRequestBytes:options.maxRequestBytes,
+            onEvent:options.onEvent,
+            port:options.port,
+            providerTimeoutMs:options.requestTimeout,
+            recipientAllowlist,
+            requestIdFactory:options.requestIdFactory,
+            retryableDelayMs:options.retryableDelayMs,
+            sendQueueTimeoutMs:options.sendQueueTimeoutMs,
+            signal:options.signal
+        });
+    }finally{
+        apiKey='';
+        appKey='';
+    }
+}
+
+export async function executeMailCommand(rawOptions={}){
+    const options=validateOptions(rawOptions);
+    switch(options.action){
+        case 'key-set':return setCredential(options);
+        case 'key-status':return credentialStatus(options);
+        case 'key-delete':return deleteCredential(options);
+        case 'send':return sendMail(options);
+        case 'serve':return serveMail(options);
+        default:usage('Unsupported Mail action.');
+    }
+}
+
+export default executeMailCommand;

package/src/sdk-browser-runtime.mjs

@@ -35,40 +35,36 @@ const expectedAiComponents=Object.freeze(
     JSON.parse(canonicalAiComponentsBytes.toString('utf8'))
 );
 
-const expectedFiles=Object.freeze([
-    ['ai/ARCANE_AI_BROWSER_WASM_COMPONENTS.json','browser-runtime/ai/ARCANE_AI_BROWSER_WASM_COMPONENTS.json','sdk-source-identity'],
-    ['ai/browser-kokoro-worker.mjs','browser-runtime/ai/browser-kokoro-worker.mjs','sdk-source-identity'],
-    ['ai/browser-speech-artifacts.mjs','browser-runtime/ai/browser-speech-artifacts.mjs','sdk-source-identity'],
-    ['ai/browser-speech-providers.mjs','browser-runtime/ai/browser-speech-providers.mjs','sdk-source-identity'],
-    ['ai/browser-speech.mjs','browser-runtime/ai/browser-speech.mjs','sdk-source-identity'],
-    ['ai/browser-wasm-llm-provider.mjs','browser-runtime/ai/browser-wasm-llm-provider.mjs','sdk-source-identity'],
-    ['ai/browser-wasm.mjs','browser-runtime/ai/browser-wasm.mjs','sdk-source-identity'],
-    ['ai/browser-whisper-worker.mjs','browser-runtime/ai/browser-whisper-worker.mjs','sdk-source-identity'],
-    ['ai/browser-wllama-runtime.mjs','browser-runtime/ai/browser-wllama-runtime.mjs','sdk-source-identity'],
-    ['ai/internal/sha256.mjs','browser-runtime/ai/internal/sha256.mjs','sdk-source-identity'],
-    ['ai/model-controller.mjs','browser-runtime/ai/model-controller.mjs','sdk-source-identity'],
-    ['ai/speech-worker-client.mjs','browser-runtime/ai/speech-worker-client.mjs','sdk-source-identity'],
-    ['ai/speech-worker-runtime.mjs','browser-runtime/ai/speech-worker-runtime.mjs','sdk-source-identity'],
-    ['ai/wllama/LICENCE','node_modules/@wllama/wllama/LICENCE','vendor-package-identity'],
-    ['ai/wllama/index.mjs','browser-runtime/ai/wllama/index.mjs','deterministic-derived-vendor'],
-    ['ai/wllama/llama.cpp-LICENSE','browser-runtime/ai/wllama/llama.cpp-LICENSE','vendor-source-identity'],
-    ['ai/wllama/wllama.wasm','node_modules/@wllama/wllama/esm/wasm/wllama.wasm','vendor-package-identity'],
-    ['dependencies/event-pubsub/index.js','node_modules/event-pubsub/index.js','vendor-package-identity'],
-    ['dependencies/event-pubsub/licence','node_modules/event-pubsub/licence','vendor-package-identity'],
-    ['dependencies/event-pubsub/package.json','node_modules/event-pubsub/package.json','vendor-package-identity'],
-    ['dependencies/strong-type/index.js','node_modules/strong-type/index.js','vendor-package-identity'],
-    ['dependencies/strong-type/licence','node_modules/strong-type/licence','vendor-package-identity'],
-    ['dependencies/strong-type/package.json','node_modules/strong-type/package.json','vendor-package-identity'],
-    ['dom-event-instrumentation.mjs','src/dom-event-instrumentation.mjs','sdk-source-identity'],
-    ['event-manager.mjs','src/event-manager.mjs','sdk-source-identity']
-].map(([filePath,sourcePath,provenance])=>Object.freeze({
-    path:filePath,sourcePath,provenance
-})));
-
-const expectedDirectories=Object.freeze([...new Set(expectedFiles.flatMap(file=>{
-    const segments=file.path.split('/');
-    return segments.slice(0,-1).map((_,index)=>segments.slice(0,index+1).join('/'));
-}))].sort(compareText));
+const admittedDependencyFiles=Object.freeze({
+    'event-pubsub':Object.freeze(['index.js','licence','package.json']),
+    'strong-type':Object.freeze(['index.js','licence','package.json'])
+});
+const exactRuntimeFileAuthorities=Object.freeze({
+    'ai/wllama/LICENCE':Object.freeze({
+        sourcePath:'node_modules/@wllama/wllama/LICENCE',
+        provenance:'vendor-package-identity'
+    }),
+    'ai/wllama/index.mjs':Object.freeze({
+        sourcePath:'browser-runtime/ai/wllama/index.mjs',
+        provenance:'deterministic-derived-vendor'
+    }),
+    'ai/wllama/llama.cpp-LICENSE':Object.freeze({
+        sourcePath:'browser-runtime/ai/wllama/llama.cpp-LICENSE',
+        provenance:'vendor-source-identity'
+    }),
+    'ai/wllama/wllama.wasm':Object.freeze({
+        sourcePath:'node_modules/@wllama/wllama/esm/wasm/wllama.wasm',
+        provenance:'vendor-package-identity'
+    }),
+    'dom-event-instrumentation.mjs':Object.freeze({
+        sourcePath:'src/dom-event-instrumentation.mjs',
+        provenance:'sdk-source-identity'
+    }),
+    'event-manager.mjs':Object.freeze({
+        sourcePath:'src/event-manager.mjs',
+        provenance:'sdk-source-identity'
+    })
+});
 
 function fail(message,code='ARCANE_SDK_BROWSER_INTEGRITY_FAILED'){
     const error=new Error(message);
@@ -101,7 +97,8 @@ function safeInventoryPath(value,label='manifest'){
     if(typeof value!=='string'||!value||value.includes('\\')||value.includes('\0')
         ||value.normalize('NFC')!==value||path.posix.isAbsolute(value)
         ||path.posix.normalize(value)!==value||value==='.'||value.startsWith('../')
-        ||value.includes('/../')){
+        ||value.includes('/../')
+        ||value.split('/').some(segment=>!segment||segment.startsWith('.'))){
         fail(`SDK browser runtime ${label} contains an unsafe path: ${String(value)}.`);
     }
     return value;
@@ -111,6 +108,46 @@ function collisionKey(value){
     return value.normalize('NFC').toLocaleLowerCase('en-US');
 }
 
+function runtimeFileAuthority(value){
+    const relative=safeInventoryPath(value);
+    const exact=Object.hasOwn(exactRuntimeFileAuthorities,relative)
+        ?exactRuntimeFileAuthorities[relative]
+        :null;
+    if(exact)return Object.freeze({path:relative,...exact});
+
+    if(relative.startsWith('ai/wllama/')){
+        fail(`SDK browser runtime Wllama asset is not admitted: ${relative}.`);
+    }
+    if(relative.startsWith('ai/')&&['.mjs','.json'].includes(path.posix.extname(relative))){
+        return Object.freeze({
+            path:relative,
+            sourcePath:`browser-runtime/${relative}`,
+            provenance:'sdk-source-identity'
+        });
+    }
+    if(relative.startsWith('dependencies/')){
+        const [directory,packageName,fileName,...extra]=relative.split('/');
+        const admitted=Object.hasOwn(admittedDependencyFiles,packageName)
+            ?admittedDependencyFiles[packageName]
+            :null;
+        if(directory==='dependencies'&&extra.length===0&&admitted?.includes(fileName)){
+            return Object.freeze({
+                path:relative,
+                sourcePath:`node_modules/${packageName}/${fileName}`,
+                provenance:'vendor-package-identity'
+            });
+        }
+    }
+    fail(`SDK browser runtime path has no admitted source authority: ${relative}.`);
+}
+
+function inventoryDirectories(files){
+    return Object.freeze([...new Set(files.flatMap(file=>{
+        const segments=file.path.split('/');
+        return segments.slice(0,-1).map((_,index)=>segments.slice(0,index+1).join('/'));
+    }))].sort(compareText));
+}
+
 function immutableInventory(files){
     return Object.freeze(files.map(file=>Object.freeze({...file})));
 }
@@ -181,7 +218,7 @@ function validateSource(source){
     });
 }
 
-function validateRelease(value){
+function validateRelease(value,{expectedContentSha256=SDK_BROWSER_RUNTIME_CONTENT_SHA256}={}){
     if(!value||typeof value!=='object'||Array.isArray(value)){
         fail('SDK browser runtime manifest must be a JSON object.');
     }
@@ -197,8 +234,8 @@ function validateRelease(value){
         fail('SDK browser runtime manifest sdkVersion is incompatible with this SDK.');
     }
     const source=validateSource(value.source);
-    if(!Array.isArray(value.files)||!Number.isSafeInteger(value.fileCount)
-        ||value.fileCount!==value.files.length||value.fileCount!==expectedFiles.length
+    if(!Array.isArray(value.files)||value.files.length===0||!Number.isSafeInteger(value.fileCount)
+        ||value.fileCount!==value.files.length
         ||!Number.isSafeInteger(value.totalBytes)||value.totalBytes<0
         ||!SHA256_PATTERN.test(value.contentSha256)){
         fail('SDK browser runtime manifest inventory summary is invalid.');
@@ -206,6 +243,7 @@ function validateRelease(value){
     let previous='';
     let totalBytes=0;
     const collisionKeys=new Set();
+    const sourceCollisionKeys=new Set();
     const files=value.files.map((entry,index)=>{
         if(!entry||typeof entry!=='object'||Array.isArray(entry)
             ||!exactKeys(entry,['bytes','path','provenance','sha256','sourcePath'])){
@@ -213,11 +251,13 @@ function validateRelease(value){
         }
         const relative=safeInventoryPath(entry.path);
         const sourcePath=safeInventoryPath(entry.sourcePath,'source inventory');
-        const expected=expectedFiles[index];
+        const expected=runtimeFileAuthority(relative);
         const key=collisionKey(relative);
+        const sourceKey=collisionKey(sourcePath);
         if(relative===MANIFEST_NAME||collisionKeys.has(key)
+            ||sourceCollisionKeys.has(sourceKey)
             ||(previous&&compareText(previous,relative)>=0)
-            ||relative!==expected.path||sourcePath!==expected.sourcePath
+            ||sourcePath!==expected.sourcePath
             ||entry.provenance!==expected.provenance){
             fail(`SDK browser runtime manifest inventory is invalid at ${relative}.`);
         }
@@ -225,6 +265,7 @@ function validateRelease(value){
             fail(`SDK browser runtime manifest metadata is invalid for ${relative}.`);
         }
         collisionKeys.add(key);
+        sourceCollisionKeys.add(sourceKey);
         previous=relative;
         totalBytes+=entry.bytes;
         if(!Number.isSafeInteger(totalBytes)){
@@ -245,12 +286,15 @@ function validateRelease(value){
     if(aggregate!==value.contentSha256){
         fail('SDK browser runtime manifest contentSha256 does not match its inventory.');
     }
-    if(value.contentSha256!==SDK_BROWSER_RUNTIME_CONTENT_SHA256){
+    if(expectedContentSha256!==null&&value.contentSha256!==expectedContentSha256){
         fail('SDK browser runtime manifest does not match the trusted SDK browser closure.');
     }
     return Object.freeze({...value,source,files:immutableInventory(files)});
 }
 
+const validatedCanonicalRelease=validateRelease(canonicalRelease,{expectedContentSha256:null});
+const expectedDirectories=inventoryDirectories(validatedCanonicalRelease.files);
+
 function sameIdentity(before,after){
     return before.dev===after.dev&&before.ino===after.ino&&before.size===after.size
         &&before.mtimeNs===after.mtimeNs&&before.ctimeNs===after.ctimeNs

package/src/testing-loader.mjs

@@ -1,9 +1,16 @@
 const TESTING_SPECIFIER='arcane-os/testing';
 const TESTING_URL=new URL('./testing.mjs',import.meta.url).href;
+const RUNTIME_STRONG_TYPE_SPECIFIER='../../node_modules/strong-type/index.js';
+const RUNTIME_ARCANE_URL=new URL('../runtime/arcane/',import.meta.url).href;
+const STRONG_TYPE_URL=new URL('../runtime/strong-type/index.js',import.meta.url).href;
 
 export function resolve(specifier,context,nextResolve){
     if(specifier===TESTING_SPECIFIER){
         return {url:TESTING_URL,shortCircuit:true};
     }
+    if(specifier===RUNTIME_STRONG_TYPE_SPECIFIER
+        &&context.parentURL?.startsWith(RUNTIME_ARCANE_URL)){
+        return {url:STRONG_TYPE_URL,shortCircuit:true};
+    }
     return nextResolve(specifier,context);
 }

package/src/toolchain.mjs

@@ -43,6 +43,7 @@ import {ArcaneError,ERROR_CODES,throwIfAborted} from './errors.mjs';
 import {createEventQueue} from './event-queue.mjs';
 import {ARCANE_MACHINE_BUNDLE_VERSION} from './constants.mjs';
 import {checkForSdkUpdate} from './update-check.mjs';
+import {executeMailCommand} from './mail.mjs';
 import {
     APP_BUNDLE_EXTENSION,
     createAppReleaseBundle,
@@ -1542,6 +1543,7 @@ export async function executeOperation(command,options={}){
         build:buildApplication,
         run:runApplication,
         'update-check':checkSdkUpdate,
+        mail:executeMailCommand,
         targets:async options=>describeTargets(options),
         repo:repositoryApplication
     };
@@ -1573,6 +1575,7 @@ export function createToolchain(defaults={}){
         build:options=>buildApplication({...defaults,...options}),
         run:options=>runApplication({...defaults,...options}),
         updateCheck:options=>checkSdkUpdate({...defaults,...options}),
+        mail:options=>executeMailCommand({...defaults,...options}),
         targets:options=>describeTargets({...defaults,...options}),
         repository:options=>repositoryApplication({...defaults,...options})
     });

package/src/workspace.mjs

@@ -476,7 +476,7 @@ function validateLock(lock,sdkDeclaration){
     return lock;
 }
 
-async function resolveInstalledSdkInstallation(workspaceRoot,declaration){
+export async function resolveInstalledSdkInstallation(workspaceRoot,declaration){
     let current=workspaceRoot;
     for(const segment of declaration.packageSource.split('/')){
         current=path.join(current,segment);