@astrale-os/sdk 0.5.0-beta.76 → 0.5.0-beta.77

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0-beta.77](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.76...sdk-v0.5.0-beta.77) (2026-08-29)
+
+
+### Features
+
+* **iframe:** declare view iframe requirements ([#327](https://github.com/astrale-os/sdk/issues/327)) ([ca2e131](https://github.com/astrale-os/sdk/commit/ca2e1311291aee3c62a19cddb33a0b4c13a345d4))
+
 ## [0.5.0-beta.76](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.75...sdk-v0.5.0-beta.76) (2026-08-29)
 
 

package/dist/application/index.d.ts

@@ -5,5 +5,5 @@ export type { AdministrationRequirements, AdministrationRequirementsInput, Calla
 export { route, routes } from './routes/index.js';
 export type { Route, RouteInput, RouteTarget, Routes } from './routes/index.js';
 export { defineFrontend, external, vite } from './view/index.js';
-export type { Frontend, FrontendInput, FrontendSource } from './view/index.js';
+export type { Frontend, FrontendInput, FrontendSource, IframeRequirements } from './view/index.js';
 export type { Application, ApplicationIdentity, RuntimeOfApplication, SchemaOfApplication, SchemaOfRuntime, } from './application.js';

package/dist/application/view/index.d.ts

@@ -1,6 +1,6 @@
 export { isFrontend } from './admission.js';
 export { defineFrontend } from './define.js';
 export type { Frontend, FrontendInput, FrontendRouteInputs, FrontendRoutes, ViewName, } from './frontend.js';
-export type { FrontendHandshake, FrontendRoute, FrontendRouteInput } from './route.js';
+export type { FrontendHandshake, FrontendRoute, FrontendRouteInput, IframeRequirements, } from './route.js';
 export { external, isFrontendSource, vite } from './source.js';
 export type { ExternalSource, FrontendSource, ViteSource } from './source.js';

package/dist/application/view/route.d.ts

@@ -1,13 +1,19 @@
 export type FrontendHandshake = 'shell' | 'none';
+export interface IframeRequirements {
+    readonly sandbox?: readonly string[];
+    readonly allow?: readonly string[];
+}
 export type FrontendRouteInput = string | {
     readonly path?: string;
     readonly document?: string;
     readonly handshake?: FrontendHandshake;
+    readonly iframe?: IframeRequirements;
 };
 export interface FrontendRoute {
     readonly path: string;
     readonly document: string;
     readonly handshake: FrontendHandshake;
+    readonly iframe?: IframeRequirements;
 }
 export declare function normalizeRoute(input: FrontendRouteInput | undefined, fallback: string): FrontendRoute;
 export declare function defaultRoute(name: string): string;

package/dist/application/view/route.js

@@ -1,22 +1,102 @@
+const TOKEN = /^[a-z][a-z0-9-]*$/u;
+const BASELINES = Object.freeze({
+    none: iframeRequirements(['allow-scripts'], []),
+    shell: iframeRequirements(['allow-same-origin', 'allow-scripts'], ['clipboard-write']),
+});
 export function normalizeRoute(input, fallback) {
     if (typeof input === 'string') {
         return Object.freeze({ path: routePath(input), document: 'index.html', handshake: 'shell' });
     }
-    const value = input ?? {};
-    if (value === null || typeof value !== 'object' || Array.isArray(value))
-        invalid();
-    if (Reflect.ownKeys(value).some((key) => key !== 'path' && key !== 'document' && key !== 'handshake')) {
+    const value = plainRecord(input ?? {});
+    if (Reflect.ownKeys(value).some((key) => typeof key !== 'string' || !['path', 'document', 'handshake', 'iframe'].includes(key))) {
         invalid();
     }
-    if (value.handshake !== undefined && value.handshake !== 'shell' && value.handshake !== 'none') {
+    const authoredHandshake = dataValue(value, 'handshake');
+    if (authoredHandshake !== undefined &&
+        authoredHandshake !== 'shell' &&
+        authoredHandshake !== 'none') {
         invalid();
     }
+    const handshake = authoredHandshake ?? 'shell';
+    const iframe = normalizeIframeRequirements(dataValue(value, 'iframe'), handshake);
+    return Object.freeze({
+        path: routePath(dataValue(value, 'path') ?? fallback),
+        document: filePath(dataValue(value, 'document') ?? 'index.html'),
+        handshake,
+        ...(iframe === undefined ? {} : { iframe }),
+    });
+}
+function normalizeIframeRequirements(input, handshake) {
+    if (input === undefined)
+        return undefined;
+    const value = plainRecord(input);
+    if (Reflect.ownKeys(value).some((key) => key !== 'sandbox' && key !== 'allow'))
+        invalid();
+    const authored = iframeRequirements(tokenArray(dataValue(value, 'sandbox')), tokenArray(dataValue(value, 'allow')));
+    assertSandboxRelationships(authored.sandbox);
+    const baseline = BASELINES[handshake];
+    const sandbox = authored.sandbox.filter((token) => !baseline.sandbox.includes(token));
+    const allow = authored.allow.filter((feature) => !baseline.allow.includes(feature));
+    return sandbox.length === 0 && allow.length === 0 ? undefined : iframeRequirements(sandbox, allow);
+}
+function iframeRequirements(sandbox, allow) {
     return Object.freeze({
-        path: routePath(value.path ?? fallback),
-        document: filePath(value.document ?? 'index.html'),
-        handshake: value.handshake ?? 'shell',
+        sandbox: Object.freeze([...new Set(sandbox)].sort()),
+        allow: Object.freeze([...new Set(allow)].sort()),
     });
 }
+function tokenArray(input) {
+    if (input === undefined)
+        return [];
+    if (!Array.isArray(input))
+        invalid();
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    const result = [];
+    for (let index = 0; index < input.length; index += 1) {
+        const descriptor = descriptors[String(index)];
+        if (descriptor === undefined || !('value' in descriptor))
+            invalid();
+        if (typeof descriptor.value !== 'string' || !TOKEN.test(descriptor.value))
+            invalid();
+        result.push(descriptor.value);
+    }
+    for (const key of Reflect.ownKeys(descriptors)) {
+        if (key === 'length')
+            continue;
+        if (typeof key !== 'string' || !/^(0|[1-9][0-9]*)$/u.test(key) || Number(key) >= input.length) {
+            invalid();
+        }
+    }
+    return result;
+}
+function plainRecord(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        invalid();
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null)
+        invalid();
+    return input;
+}
+function dataValue(input, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (descriptor === undefined)
+        return undefined;
+    if (!('value' in descriptor))
+        invalid();
+    return descriptor.value;
+}
+function assertSandboxRelationships(sandbox) {
+    const tokens = new Set(sandbox);
+    if (tokens.has('allow-popups-to-escape-sandbox') && !tokens.has('allow-popups'))
+        invalid();
+    if (tokens.has('allow-top-navigation') && tokens.has('allow-top-navigation-by-user-activation')) {
+        invalid();
+    }
+    if (tokens.has('allow-top-navigation-to-custom-protocols') &&
+        (tokens.has('allow-top-navigation') || tokens.has('allow-popups'))) {
+        invalid();
+    }
+}
 export function defaultRoute(name) {
     return routePath(`/${name
         .replace(/([a-z0-9])([A-Z])/gu, '$1-$2')

package/dist/deployment/build/frontend/compilation.d.ts

@@ -1,5 +1,5 @@
 import type { Frontend, FrontendSource } from '../../../application/view/index.js';
-import type { FrontendHandshake } from '../../../application/view/index.js';
+import type { FrontendHandshake, IframeRequirements } from '../../../application/view/index.js';
 import type { Key, ViewRef } from '../../../platform/schema/index.js';
 import type { Domain } from '../../../platform/schema/index.js';
 export interface CompiledFrontendRoute {
@@ -7,6 +7,7 @@ export interface CompiledFrontendRoute {
     readonly path: string;
     readonly document: string;
     readonly handshake: FrontendHandshake;
+    readonly iframe?: IframeRequirements;
 }
 export interface FrontendCompilation {
     readonly source: FrontendSource;

package/dist/deployment/build/frontend/compilation.js

@@ -15,6 +15,7 @@ export function compileFrontend(frontend, domain) {
             path: route.path,
             document: route.document,
             handshake: route.handshake,
+            ...(route.iframe === undefined ? {} : { iframe: route.iframe }),
         });
     });
     const entrypoint = domain.views[frontend.entrypoint];

package/dist/deployment/release/publication/views.js

@@ -8,5 +8,6 @@ export function views(build, addressing) {
         view: route.view,
         href: new URL(route.path.replace(/^\//u, ''), base).href,
         handshake: route.handshake,
+        ...(route.iframe === undefined ? {} : { iframe: route.iframe }),
     })));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.76",
+  "version": "0.5.0-beta.77",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -217,11 +217,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@astrale-os/kernel-client": "0.6.0-beta.29",
-    "@astrale-os/kernel-core": "0.9.0-beta.22",
+    "@astrale-os/kernel-client": "0.6.0-beta.30",
+    "@astrale-os/kernel-core": "0.9.0-beta.23",
     "@astrale-os/kernel-dsl": "0.2.0-beta.17",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.23",
-    "@astrale-os/kernel-server": "0.5.0-beta.25",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.24",
+    "@astrale-os/kernel-server": "0.5.0-beta.26",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "hono": "^4.13.2",
     "jose": "^6.2.9",