@astrale-os/shell 0.1.0

package/dist/application/windowing/token-refresh.js

@@ -0,0 +1,60 @@
+import { REFRESH_WINDOW_MS } from '../../domain/identity/delegation';
+const BACKOFF_DELAYS_MS = [1_000, 2_000, 4_000];
+export function createTokenRefresher(config) {
+    const now = config.now ?? Date.now;
+    let timer = null;
+    let stopped = false;
+    function schedule() {
+        if (stopped)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        const token = config.token();
+        const leadTimeMs = Math.max(token.expiresAt - now() - REFRESH_WINDOW_MS, 0);
+        timer = setTimeout(() => {
+            void runRefresh();
+        }, leadTimeMs);
+    }
+    async function runRefresh() {
+        for (let attempt = 0; attempt <= BACKOFF_DELAYS_MS.length; attempt += 1) {
+            if (stopped)
+                return;
+            try {
+                const next = await config.mint();
+                config.setToken({
+                    credential: next.credential,
+                    expiresAt: next.expiresAt,
+                    issuedAt: now(),
+                    scope: { functionId: config.functionId },
+                });
+                schedule();
+                return;
+            }
+            catch (err) {
+                if (attempt === BACKOFF_DELAYS_MS.length) {
+                    config.onFailure?.(err);
+                    return;
+                }
+                await delay(BACKOFF_DELAYS_MS[attempt]);
+            }
+        }
+    }
+    return {
+        start() {
+            stopped = false;
+            schedule();
+        },
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+        },
+        async forceRefreshNow() {
+            await runRefresh();
+        },
+    };
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/domain/identity/delegation.d.ts

@@ -0,0 +1,15 @@
+export type DelegationScope = {
+    readonly functionId: string;
+};
+export type DelegationToken = {
+    readonly credential: string;
+    readonly scope: DelegationScope;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+};
+export type TokenState = 'fresh' | 'expiring' | 'expired' | 'refreshing' | 'failed';
+/** How long before expiration we start proactively refreshing. */
+export declare const REFRESH_WINDOW_MS = 120000;
+export declare function stateOf(token: DelegationToken, now?: number): TokenState;
+export declare function isExpired(token: DelegationToken, now?: number): boolean;
+//# sourceMappingURL=delegation.d.ts.map

package/dist/domain/identity/delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../../../src/domain/identity/delegation.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAA;AAEnF,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,SAAU,CAAA;AAExC,wBAAgB,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,SAAa,GAAG,UAAU,CAI5E;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,SAAa,GAAG,OAAO,CAE3E"}

package/dist/domain/identity/delegation.js

@@ -0,0 +1,12 @@
+/** How long before expiration we start proactively refreshing. */
+export const REFRESH_WINDOW_MS = 120_000;
+export function stateOf(token, now = Date.now()) {
+    if (token.expiresAt <= now)
+        return 'expired';
+    if (token.expiresAt - now <= REFRESH_WINDOW_MS)
+        return 'expiring';
+    return 'fresh';
+}
+export function isExpired(token, now = Date.now()) {
+    return token.expiresAt <= now;
+}

package/dist/domain/identity/path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Built-in kernel root identity, used as the default mint subject when no
+ * explicit `mintIdentity` is configured.
+ */
+export declare const SYSTEM_IDENTITY = "__system__";
+/**
+ * Address a method on an identity or path: `@<id>::method` for a bare node id,
+ * `<path>::method` for an absolute path (one starting with `/`).
+ */
+export declare function identityMethod(identity: string, method: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/domain/identity/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/domain/identity/path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,eAAe,eAAe,CAAA;AAE3C;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGvE"}

package/dist/domain/identity/path.js

@@ -0,0 +1,13 @@
+/**
+ * Built-in kernel root identity, used as the default mint subject when no
+ * explicit `mintIdentity` is configured.
+ */
+export const SYSTEM_IDENTITY = '__system__';
+/**
+ * Address a method on an identity or path: `@<id>::method` for a bare node id,
+ * `<path>::method` for an absolute path (one starting with `/`).
+ */
+export function identityMethod(identity, method) {
+    const target = identity.startsWith('/') ? identity : `@${identity}`;
+    return `${target}::${method}`;
+}

package/dist/domain/identity/resolve-self.d.ts

@@ -0,0 +1,21 @@
+/** Kernel path that returns the AUTHENTICATED caller's own identity node. */
+export declare const WHOAMI_PATH = "/:kernel.astrale.ai:interface.Identity:whoami";
+/**
+ * Resolve the mint SUBJECT — the identity node a delegation/credential should be
+ * minted for. It MUST be the principal the kernel actually authenticates this
+ * caller as, otherwise the minted token impersonates someone else.
+ *
+ * Why a kernel round-trip and not the local credential: a cookie-fronted SPA
+ * holds an EMPTY credential string (the session token lives in an httpOnly
+ * cookie it can't read), so the subject cannot be derived locally. We ask the
+ * kernel via `whoami`; that request carries the cookie, so the router unseals it
+ * and the kernel answers with the logged-in user's node. Without this the shell
+ * defaulted every mint to `__system__`, so a View iframe mounted by a logged-in
+ * user acted as the kernel ROOT instead of as that user.
+ *
+ * `fallback` (the configured `mintIdentity`, default `__system__`) is used when
+ * whoami can't be resolved — a genuinely system/dev caller, or an unauthenticated
+ * boot. The result is cached: the principal is stable for a session.
+ */
+export declare function createSelfResolver(fallback?: string): (whoami: () => Promise<unknown>) => Promise<string>;
+//# sourceMappingURL=resolve-self.d.ts.map

package/dist/domain/identity/resolve-self.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-self.d.ts","sourceRoot":"","sources":["../../../src/domain/identity/resolve-self.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,eAAO,MAAM,WAAW,kDAAkD,CAAA;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,GAAE,MAAwB,GACjC,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAarD"}

package/dist/domain/identity/resolve-self.js

@@ -0,0 +1,36 @@
+import { SYSTEM_IDENTITY } from './path';
+/** Kernel path that returns the AUTHENTICATED caller's own identity node. */
+export const WHOAMI_PATH = '/:kernel.astrale.ai:interface.Identity:whoami';
+/**
+ * Resolve the mint SUBJECT — the identity node a delegation/credential should be
+ * minted for. It MUST be the principal the kernel actually authenticates this
+ * caller as, otherwise the minted token impersonates someone else.
+ *
+ * Why a kernel round-trip and not the local credential: a cookie-fronted SPA
+ * holds an EMPTY credential string (the session token lives in an httpOnly
+ * cookie it can't read), so the subject cannot be derived locally. We ask the
+ * kernel via `whoami`; that request carries the cookie, so the router unseals it
+ * and the kernel answers with the logged-in user's node. Without this the shell
+ * defaulted every mint to `__system__`, so a View iframe mounted by a logged-in
+ * user acted as the kernel ROOT instead of as that user.
+ *
+ * `fallback` (the configured `mintIdentity`, default `__system__`) is used when
+ * whoami can't be resolved — a genuinely system/dev caller, or an unauthenticated
+ * boot. The result is cached: the principal is stable for a session.
+ */
+export function createSelfResolver(fallback = SYSTEM_IDENTITY) {
+    let cached;
+    return async (whoami) => {
+        if (cached !== undefined)
+            return cached;
+        try {
+            const me = (await whoami());
+            const id = me && typeof me.id === 'string' && me.id.length > 0 ? me.id : undefined;
+            cached = id ?? fallback;
+        }
+        catch {
+            cached = fallback;
+        }
+        return cached;
+    };
+}

package/dist/domain/intent/middleware/capabilities.d.ts

@@ -0,0 +1,28 @@
+import type { IntentRegistry } from '../../message/registries';
+import type { WindowCapabilities } from '../../window/config';
+import type { IntentMiddleware } from '../pipeline';
+export type CapabilityLookup = (sender: string) => WindowCapabilities | undefined;
+export type CapabilityViolation = {
+    readonly sender: string;
+    readonly intent: keyof IntentRegistry;
+};
+export type CapabilitiesConfig = {
+    /**
+     * Map each sender windowId to its declared capabilities. Intents whose
+     * name is absent from the sender's capability list are blocked.
+     */
+    readonly lookup: CapabilityLookup;
+    /**
+     * Called when an intent is blocked. The violation can be used to emit
+     * an ErrorMessage back to the sender (shell wiring does that separately).
+     */
+    readonly onViolation?: (violation: CapabilityViolation) => void;
+    /**
+     * If true, intents originated by the shell itself (sender === selfWindowId)
+     * are never filtered. Default: true.
+     */
+    readonly allowSelf?: boolean;
+    readonly selfWindowId?: string;
+};
+export declare function capabilitiesMiddleware(config: CapabilitiesConfig): IntentMiddleware;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/domain/intent/middleware/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../../src/domain/intent/middleware/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,kBAAkB,GAAG,SAAS,CAAA;AAEjF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,cAAc,CAAA;CACtC,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IAEjC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAE/D;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAE5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,gBAAgB,CAkBnF"}

package/dist/domain/intent/middleware/capabilities.js

@@ -0,0 +1,18 @@
+export function capabilitiesMiddleware(config) {
+    const { lookup, onViolation, selfWindowId } = config;
+    const allowSelf = config.allowSelf ?? true;
+    return async (message, next) => {
+        const sender = message.envelope.sender.windowId;
+        if (allowSelf && selfWindowId !== undefined && sender === selfWindowId) {
+            await next();
+            return;
+        }
+        const caps = lookup(sender);
+        const intentName = message.envelope.name;
+        if (!caps || !caps.intents.includes(intentName)) {
+            onViolation?.({ sender, intent: intentName });
+            return;
+        }
+        await next();
+    };
+}

package/dist/domain/intent/middleware/logging.d.ts

@@ -0,0 +1,14 @@
+import type { IntentMiddleware } from '../pipeline';
+export type LoggingSink = (entry: LoggingEntry) => void;
+export type LoggingEntry = {
+    readonly name: string;
+    readonly sender: string;
+    readonly correlationId?: string;
+    readonly phase: 'in' | 'out';
+    readonly timestamp: number;
+};
+export type LoggingConfig = {
+    readonly sink?: LoggingSink;
+};
+export declare function loggingMiddleware(config?: LoggingConfig): IntentMiddleware;
+//# sourceMappingURL=logging.d.ts.map

package/dist/domain/intent/middleware/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../../src/domain/intent/middleware/logging.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;AAEvD,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,KAAK,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAC5B,CAAA;AAED,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,aAAkB,GAAG,gBAAgB,CAQ9E"}

package/dist/domain/intent/middleware/logging.js

@@ -0,0 +1,21 @@
+export function loggingMiddleware(config = {}) {
+    const sink = config.sink ?? defaultSink;
+    return async (message, next) => {
+        sink(toEntry(message, 'in'));
+        await next();
+        sink(toEntry(message, 'out'));
+    };
+}
+function toEntry(message, phase) {
+    return {
+        name: message.envelope.name,
+        sender: message.envelope.sender.windowId,
+        correlationId: message.envelope.correlationId,
+        phase,
+        timestamp: Date.now(),
+    };
+}
+function defaultSink(entry) {
+    // eslint-disable-next-line no-console -- built-in sink; opt-in via wiring.
+    console.debug(`[shell.intent] ${entry.phase} ${entry.name} from=${entry.sender}${entry.correlationId ? ` corr=${entry.correlationId}` : ''}`);
+}

package/dist/domain/intent/middleware/rate-limit.d.ts

@@ -0,0 +1,20 @@
+import type { IntentMessage } from '../../message/types';
+import type { IntentMiddleware } from '../pipeline';
+export type RateLimitKey = (message: IntentMessage) => string;
+export type RateLimitViolation = {
+    readonly key: string;
+    readonly intent: string;
+};
+export type RateLimitConfig = {
+    readonly windowMs: number;
+    readonly max: number;
+    readonly key?: RateLimitKey;
+    readonly onViolation?: (violation: RateLimitViolation) => void;
+};
+/**
+ * Fixed-window rate limiter. An amortized sweep evicts expired buckets on
+ * every `windowMs` interval of activity so the map stays bounded by the
+ * number of active keys, not the total ever seen.
+ */
+export declare function rateLimitMiddleware(config: RateLimitConfig): IntentMiddleware;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/domain/intent/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../../src/domain/intent/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,CAAA;AAE7D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,kBAAkB,KAAK,IAAI,CAAA;CAC/D,CAAA;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CA+B7E"}

package/dist/domain/intent/middleware/rate-limit.js

@@ -0,0 +1,33 @@
+/**
+ * Fixed-window rate limiter. An amortized sweep evicts expired buckets on
+ * every `windowMs` interval of activity so the map stays bounded by the
+ * number of active keys, not the total ever seen.
+ */
+export function rateLimitMiddleware(config) {
+    const { windowMs, max, onViolation } = config;
+    const key = config.key ?? ((m) => `${m.envelope.sender.windowId}|${m.envelope.name}`);
+    const buckets = new Map();
+    let nextSweepAt = 0;
+    return async (message, next) => {
+        const k = key(message);
+        const now = Date.now();
+        if (now >= nextSweepAt) {
+            for (const [bucketKey, bucket] of buckets) {
+                if (bucket.resetAt <= now)
+                    buckets.delete(bucketKey);
+            }
+            nextSweepAt = now + windowMs;
+        }
+        let bucket = buckets.get(k);
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = { count: 0, resetAt: now + windowMs };
+            buckets.set(k, bucket);
+        }
+        bucket.count += 1;
+        if (bucket.count > max) {
+            onViolation?.({ key: k, intent: message.envelope.name });
+            return;
+        }
+        await next();
+    };
+}

package/dist/domain/intent/pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { IntentMessage } from '../message/types';
+export type IntentMiddleware = (message: IntentMessage, next: () => Promise<void>) => Promise<void>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/domain/intent/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../src/domain/intent/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/dist/domain/intent/pipeline.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/intent/router.d.ts

@@ -0,0 +1,6 @@
+import type { IntentRegistry } from '../message/registries';
+import type { IntentMessage } from '../message/types';
+export interface IntentRouter {
+    dispatch<K extends keyof IntentRegistry>(message: IntentMessage<K>): Promise<void>;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/domain/intent/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/domain/intent/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnF"}

package/dist/domain/intent/router.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/message/errors.d.ts

@@ -0,0 +1,2 @@
+export type ErrorCode = 'HANDSHAKE_TIMEOUT' | 'ORIGIN_MISMATCH' | 'WINDOW_UNAVAILABLE' | 'UNSUPPORTED_VERSION' | 'INTENT_NOT_ALLOWED' | 'DELIVERY_FAILED' | 'TOKEN_REFRESH_FAILED' | 'NO_VIEW_AVAILABLE';
+//# sourceMappingURL=errors.d.ts.map

package/dist/domain/message/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/domain/message/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,sBAAsB,GACtB,mBAAmB,CAAA"}

package/dist/domain/message/errors.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/message/registries.d.ts

@@ -0,0 +1,145 @@
+export interface ViewRef {
+    readonly viewId: string;
+    readonly functionId: string;
+    readonly label?: string;
+}
+/**
+ * Intent registry — extensible via declaration merging.
+ *
+ * Consumers extend via:
+ *   declare module '@astrale-os/shell' {
+ *     interface IntentRegistry { ... }
+ *   }
+ */
+export interface IntentRegistry {
+    open: {
+        payload: {
+            nodeId: string;
+            viewId?: string;
+        };
+        response: {
+            windowId: string;
+        };
+    };
+    close: {
+        payload: {
+            windowId: string;
+        };
+        response: void;
+    };
+    focus: {
+        payload: {
+            nodeId: string;
+        };
+        response: void;
+    };
+    willClose: {
+        payload: Record<string, never>;
+        response: void;
+    };
+    closeAck: {
+        payload: Record<string, never>;
+        response: void;
+    };
+    closeRefuse: {
+        payload: {
+            reason: string;
+        };
+        response: void;
+    };
+    pickView: {
+        payload: {
+            views: ViewRef[];
+        };
+        response: {
+            viewId: string;
+        };
+    };
+    receive: {
+        payload: {
+            data: unknown;
+            sourceIntent: string;
+        };
+        response: void;
+    };
+    /**
+     * Hot-swap — parent pushes a new target node to an already-mounted view
+     * without remounting. The child reads `targetNodeId` at handshake time
+     * for the initial value; `setTarget` replaces it for the lifetime of the
+     * window.
+     */
+    setTarget: {
+        payload: {
+            nodeId: string;
+        };
+        response: void;
+    };
+    /**
+     * Child → parent: a view asks the user to grant `perms` (a permission
+     * bitmask) on `node` to `identity` (the beneficiary subject). Both `node`
+     * and `identity` are bare node ids (e.g. the view's `targetNodeId`, or
+     * `whoami().id` for "grant to myself") — the root shell addresses them as
+     * `@<id>`. The root shell (GUI) surfaces a modal, computes the delta vs.
+     * what the subject already holds, and — on approval — grants only the
+     * missing bits under the GUI user's own credential. `reason` is shown to
+     * the user. `response.perms` is the bitmask actually granted (0 if
+     * declined / nothing was missing).
+     *
+     * Reaches a handler only from a view mounted as a DIRECT child of the root
+     * shell — the default intent policy does not bubble past one hop.
+     */
+    requestAccess: {
+        payload: {
+            node: string;
+            identity: string;
+            perms: number;
+            reason?: string;
+        };
+        response: {
+            granted: boolean;
+            perms: number;
+        };
+    };
+    /**
+     * Generic correlated reply channel. The default intent transport is
+     * fire-and-forget; `requestIntent()` sends an intent carrying a
+     * `correlationId` and awaits an `intentReply` whose payload echoes it back
+     * with the handler's `result`. Routed to the resolver purely by
+     * `correlationId` — it intentionally matches no local handler.
+     */
+    intentReply: {
+        payload: {
+            correlationId: string;
+            result: unknown;
+        };
+        response: void;
+    };
+}
+/**
+ * Control message registry — extensible via declaration merging.
+ */
+export interface CtrlRegistry {
+    handshake: {
+        data: {
+            delegationToken: string;
+            tokenExpiresAt: number;
+            windowId: string;
+            kernelUrl: string;
+            functionId: string;
+            targetNodeId?: string;
+            mintIdentity?: string;
+        };
+    };
+    handshakeAck: {
+        data: {
+            windowId: string;
+        };
+    };
+    tokenRefresh: {
+        data: {
+            delegationToken: string;
+            tokenExpiresAt: number;
+        };
+    };
+}
+//# sourceMappingURL=registries.d.ts.map

package/dist/domain/message/registries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registries.d.ts","sourceRoot":"","sources":["../../../src/domain/message/registries.ts"],"names":[],"mappings":"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"}

package/dist/domain/message/registries.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/message/types.d.ts

@@ -0,0 +1,30 @@
+import type { ErrorCode } from './errors';
+import type { CtrlRegistry, IntentRegistry } from './registries';
+export type IntentEnvelope<K extends keyof IntentRegistry = keyof IntentRegistry> = {
+    readonly name: K;
+    readonly payload: IntentRegistry[K]['payload'];
+    readonly sender: {
+        readonly windowId: string;
+    };
+    readonly correlationId?: string;
+};
+export type IntentMessage<K extends keyof IntentRegistry = keyof IntentRegistry> = {
+    readonly type: 'intent';
+    readonly version: 1;
+    readonly envelope: IntentEnvelope<K>;
+};
+export type CtrlMessage<K extends keyof CtrlRegistry = keyof CtrlRegistry> = {
+    readonly type: 'ctrl';
+    readonly version: 1;
+    readonly action: K;
+    readonly data: CtrlRegistry[K]['data'];
+};
+export type ErrorMessage = {
+    readonly type: 'error';
+    readonly version: 1;
+    readonly code: ErrorCode;
+    readonly message: string;
+    readonly context?: unknown;
+};
+export type ShellMessage = IntentMessage | CtrlMessage | ErrorMessage;
+//# sourceMappingURL=types.d.ts.map

package/dist/domain/message/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/domain/message/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAEhE,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,cAAc,IAAI;IAClF,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IAChB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC9C,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC,CAAA;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,cAAc,IAAI;IACjF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,YAAY,GAAG,MAAM,YAAY,IAAI;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IAClB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;CACvC,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,WAAW,GAAG,YAAY,CAAA"}

package/dist/domain/message/types.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/window/config.d.ts

@@ -0,0 +1,26 @@
+import type { IntentRegistry } from '../message/registries';
+export interface SandboxProfile {
+    readonly allowScripts: boolean;
+    readonly allowForms: boolean;
+    readonly allowPopups: boolean;
+    readonly allowSameOrigin: boolean;
+    readonly allowModals: boolean;
+}
+export interface WindowCapabilities {
+    readonly intents: ReadonlyArray<keyof IntentRegistry>;
+}
+export interface WindowConfig {
+    readonly functionId: string;
+    readonly isolation: 'sandboxed' | 'shared';
+    readonly capabilities: WindowCapabilities;
+    /**
+     * Sandbox profile for the iframe.
+     * - `undefined` → adapter default (`DEFAULT_SANDBOX` in iframe.shell-adapter).
+     * - `SandboxProfile` → explicit flag set, becomes the `sandbox=…` attribute.
+     * - `null` → opt out: no `sandbox` attribute on the iframe at all (the
+     *   browser's cross-origin policy is the only remaining isolation). Used
+     *   for first-party trusted views per the GUI allowlist.
+     */
+    readonly sandbox?: SandboxProfile | null;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/domain/window/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/domain/window/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAE3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,cAAc,CAAC,CAAA;CACtD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,QAAQ,CAAA;IAC1C,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;CACzC"}

package/dist/domain/window/config.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/window/lifecycle.d.ts

@@ -0,0 +1,27 @@
+import type { WindowState } from './window';
+export type LifecycleEvent = {
+    kind: 'hide';
+} | {
+    kind: 'restore';
+} | {
+    kind: 'requestClose';
+} | {
+    kind: 'closeAck';
+} | {
+    kind: 'closeRefuse';
+} | {
+    kind: 'forceClose';
+};
+export type TransitionResult = {
+    ok: true;
+    next: WindowState;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Pure state-machine transition. Used by the lifecycle controller —
+ * no timers, no side effects here.
+ */
+export declare function transition(state: WindowState, event: LifecycleEvent): TransitionResult;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/domain/window/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/domain/window/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAA;AAE1B,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9F;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAsBtF"}