@astrale-os/kernel-protocol 0.5.0-beta.23 → 0.5.0-beta.25

package/CHANGELOG.md

@@ -24,6 +24,29 @@
 * the first supported V2 release is a coordinated `1.0.0`, not a compatible continuation of the
   current `0.x` line; package and wire versions remain independent as specified in
   [the protocol architecture](./.spec/architecture.md)
+## [0.5.0-beta.25](https://github.com/astrale-os/kernel/compare/kernel-protocol-v0.5.0-beta.24...kernel-protocol-v0.5.0-beta.25) (2026-08-29)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @astrale-os/kernel-core bumped to 0.9.0-beta.24
+
+## [0.5.0-beta.24](https://github.com/astrale-os/kernel/compare/kernel-protocol-v0.5.0-beta.23...kernel-protocol-v0.5.0-beta.24) (2026-08-29)
+
+
+### Features
+
+* **api:** carry view iframe requirements ([#531](https://github.com/astrale-os/kernel/issues/531)) ([4eedb0b](https://github.com/astrale-os/kernel/commit/4eedb0b3430f5f642942e913cf1c5806e09b7cf1))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @astrale-os/kernel-core bumped to 0.9.0-beta.23
+
 ## [0.5.0-beta.23](https://github.com/astrale-os/kernel/compare/kernel-protocol-v0.5.0-beta.22...kernel-protocol-v0.5.0-beta.23) (2026-08-29)
 
 

package/dist/publication/bindings/index.d.ts

@@ -1,3 +1,3 @@
 export { admitCallableBinding, admitCallableKey, type CallableBinding } from './callable.js';
 export { acceptInvocationEndpoints, type InvocationEndpoints } from './invocation.js';
-export { admitViewBinding, type ViewBinding } from './view.js';
+export { admitViewBinding, type IframeRequirements, type ViewBinding } from './view.js';

package/dist/publication/bindings/view.d.ts

@@ -3,5 +3,12 @@ export interface ViewBinding {
     readonly view: Key.View;
     readonly href: string;
     readonly handshake: 'shell' | 'none';
+    readonly iframe?: IframeRequirements;
+}
+export interface IframeRequirements {
+    readonly sandbox?: readonly string[];
+    readonly allow?: readonly string[];
 }
 export declare function admitViewBinding(input: unknown, origin: string): ViewBinding;
+/** Authoring-only normalization used before a Publication receives its canonical ETag. */
+export declare function canonicalizeViewBinding(input: unknown, origin: string): ViewBinding;

package/dist/publication/bindings/view.js

@@ -1,9 +1,17 @@
 import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
 import { absoluteHttpUrl, exact, record } from '../content.js';
 import { fail } from '../error.js';
+const TOKEN = /^[a-z][a-z0-9-]*$/u;
 export function admitViewBinding(input, origin) {
+    return readViewBinding(input, origin, false);
+}
+/** Authoring-only normalization used before a Publication receives its canonical ETag. */
+export function canonicalizeViewBinding(input, origin) {
+    return readViewBinding(input, origin, true);
+}
+function readViewBinding(input, origin, canonicalize) {
     const value = record(input, 'PUBLICATION_VIEW_INVALID', 'Published View binding is invalid.');
-    exact(value, ['view', 'href', 'handshake'], 'PUBLICATION_VIEW_INVALID');
+    exact(value, ['view', 'href', 'handshake', 'iframe'], 'PUBLICATION_VIEW_INVALID');
     let view;
     try {
         view = Key(String(value.view));
@@ -20,9 +28,110 @@ export function admitViewBinding(input, origin) {
     if (value.handshake !== 'shell' && value.handshake !== 'none') {
         fail('PUBLICATION_VIEW_INVALID', 'View handshake is invalid.');
     }
+    const iframe = admitIframeRequirements(dataValue(value, 'iframe'), value.handshake, canonicalize);
     return Object.freeze({
         view,
         href: absoluteHttpUrl(value.href, true, 'PUBLICATION_VIEW_INVALID'),
         handshake: value.handshake,
+        ...(iframe === undefined ? {} : { iframe }),
+    });
+}
+function admitIframeRequirements(input, handshake, canonicalize) {
+    if (input === undefined)
+        return undefined;
+    const value = plainRecord(input);
+    exactOwnKeys(value, ['sandbox', 'allow']);
+    if (!canonicalize && (!Object.hasOwn(value, 'sandbox') || !Object.hasOwn(value, 'allow'))) {
+        invalid();
+    }
+    const sandbox = tokens(dataValue(value, 'sandbox'), canonicalize);
+    const allow = tokens(dataValue(value, 'allow'), canonicalize);
+    assertRelationships(sandbox);
+    const baselineSandbox = handshake === 'shell' ? ['allow-same-origin', 'allow-scripts'] : ['allow-scripts'];
+    const baselineAllow = handshake === 'shell' ? ['clipboard-write'] : [];
+    if (!canonicalize &&
+        (sandbox.some((token) => baselineSandbox.includes(token)) ||
+            allow.some((feature) => baselineAllow.includes(feature)))) {
+        invalid();
+    }
+    const canonicalSandbox = canonicalize
+        ? sandbox.filter((token) => !baselineSandbox.includes(token))
+        : sandbox;
+    const canonicalAllow = canonicalize
+        ? allow.filter((feature) => !baselineAllow.includes(feature))
+        : allow;
+    if (!canonicalize && canonicalSandbox.length === 0 && canonicalAllow.length === 0)
+        invalid();
+    if (canonicalSandbox.length === 0 && canonicalAllow.length === 0)
+        return undefined;
+    return Object.freeze({
+        sandbox: Object.freeze(canonicalSandbox),
+        allow: Object.freeze(canonicalAllow),
     });
 }
+function plainRecord(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null)
+        invalid();
+    return input;
+}
+function exactOwnKeys(input, allowed) {
+    const keys = new Set(allowed);
+    if (Reflect.ownKeys(input).some((key) => typeof key !== 'string' || !keys.has(key)))
+        invalid();
+}
+function dataValue(input, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (descriptor === undefined)
+        return undefined;
+    if (!('value' in descriptor))
+        invalid();
+    return descriptor.value;
+}
+function tokens(input, canonicalize) {
+    if (input === undefined)
+        return [];
+    if (!Array.isArray(input))
+        invalid();
+    const descriptors = Object.getOwnPropertyDescriptors(input);
+    const values = [];
+    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();
+        values.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();
+        }
+    }
+    if (canonicalize)
+        return [...new Set(values)].sort();
+    for (let index = 1; index < values.length; index += 1) {
+        if (values[index - 1] >= values[index])
+            invalid();
+    }
+    return values;
+}
+function assertRelationships(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();
+    }
+}
+function invalid() {
+    return fail('PUBLICATION_VIEW_INVALID', 'View iframe requirements are invalid.');
+}

package/dist/publication/index.d.ts

@@ -14,4 +14,4 @@ export { ClassOperationOrder, admitRequirements, validateRequirements, type Capa
 export { acceptReference, compareReference, compareReferences, matchesReference, reference, type PublicationRef, type PublicationReferenceRelation, } from './reference.js';
 export type { BodyPick, CredentialSource, HttpMethod, HttpRoute, HttpRouteDeclaration, RouteBody, RouteHeaders, SingleCredentialSource, } from './route.js';
 export type { Schema } from './schema.js';
-export { acceptInvocationEndpoints, type CallableBinding, type InvocationEndpoints, type ViewBinding, } from './bindings/index.js';
+export { acceptInvocationEndpoints, type CallableBinding, type IframeRequirements, type InvocationEndpoints, type ViewBinding, } from './bindings/index.js';

package/dist/publication/publication.js

@@ -3,6 +3,7 @@ import { accept as acceptIssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import { Key, patterns } from '@astrale-os/kernel-dsl/v1/addressing';
 import * as portable from '@astrale-os/kernel-dsl/value';
 import { admitCallableBinding, admitViewBinding } from './bindings/index.js';
+import { canonicalizeViewBinding } from './bindings/view.js';
 import { array, deepFreeze, exact, record, unique } from './content.js';
 import { admitEndpoint as admitDeliveryEndpoint } from './delivery-endpoint.js';
 import { fail } from './error.js';
@@ -33,7 +34,8 @@ export function url(input) {
     return `${admitted.replace(/\/+$/u, '')}${PATH}`;
 }
 export function seal(input) {
-    return acceptPublication({ ...input, etag: computeEtag(input) }, false);
+    const canonical = withoutEtag(acceptPublication({ ...input, etag: 'canonicalizing' }, false, true));
+    return acceptPublication({ ...canonical, etag: computeEtag(canonical) }, false);
 }
 export function accept(input) {
     const publication = acceptPublication(input, true);
@@ -45,7 +47,7 @@ export function accept(input) {
 export function encode(input) {
     return portable.json.encode(input);
 }
-function acceptPublication(input, requireEtag) {
+function acceptPublication(input, requireEtag, canonicalizeViews = false) {
     const value = record(input, 'PUBLICATION_INVALID', 'Expected a Publication object.');
     exact(value, [
         'format',
@@ -80,7 +82,7 @@ function acceptPublication(input, requireEtag) {
     exact(bindingSet, ['callables', 'views'], 'PUBLICATION_BINDING_INVALID');
     const callables = array(bindingSet.callables, 'PUBLICATION_BINDING_INVALID').map((entry) => admitCallableBinding(entry, origin));
     unique(callables.map(({ callable }) => callable), 'PUBLICATION_BINDING_INVALID', 'callable binding');
-    const views = array(bindingSet.views, 'PUBLICATION_VIEW_INVALID').map((entry) => admitViewBinding(entry, origin));
+    const views = array(bindingSet.views, 'PUBLICATION_VIEW_INVALID').map((entry) => canonicalizeViews ? canonicalizeViewBinding(entry, origin) : admitViewBinding(entry, origin));
     unique(views.map(({ view }) => view), 'PUBLICATION_VIEW_INVALID', 'View binding');
     const routes = array(value.routes, 'PUBLICATION_ROUTE_INVALID').map((entry) => admitRoute(entry, origin));
     unique(routes.map(({ name }) => name), 'PUBLICATION_ROUTE_INVALID', 'route name');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-protocol",
-  "version": "0.5.0-beta.23",
+  "version": "0.5.0-beta.25",
   "description": "Portable Astrale invocation, publication, installation, routing, and issuer protocols",
   "license": "Apache-2.0",
   "repository": {
@@ -133,7 +133,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.22",
+    "@astrale-os/kernel-core": "0.9.0-beta.24",
     "@astrale-os/kernel-dsl": "0.2.0-beta.17",
     "@noble/hashes": "2.3.0"
   },