@astrale-os/kernel-protocol 0.5.0-beta.68 → 0.5.0-beta.69

package/dist/issuer/claims.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Private JWT claim of the self credential a durable step's Domain signs for the Kernel: the id of
+ * the Execution the step belongs to. After a consented issuer change, the Kernel accepts the
+ * replaced issuer past its window only for a credential naming an unfinished run of its Domain
+ * that was in flight at that change.
+ */
+export declare const EXECUTION_CLAIM = "execution";

package/dist/issuer/claims.js

@@ -0,0 +1,7 @@
+/**
+ * Private JWT claim of the self credential a durable step's Domain signs for the Kernel: the id of
+ * the Execution the step belongs to. After a consented issuer change, the Kernel accepts the
+ * replaced issuer past its window only for a credential naming an unfinished run of its Domain
+ * that was in flight at that change.
+ */
+export const EXECUTION_CLAIM = 'execution';

package/dist/issuer/index.d.ts

@@ -1,3 +1,4 @@
+export { EXECUTION_CLAIM } from './claims.js';
 export { acceptConfiguration, configuration, type Configuration, type ConfigurationOptions, } from './configuration.js';
 export { DiscoveryError, type DiscoveryErrorCode } from './error.js';
 export { hosted } from './hosted.js';

package/dist/issuer/index.js

@@ -1,3 +1,4 @@
+export { EXECUTION_CLAIM } from './claims.js';
 export { acceptConfiguration, configuration, } from './configuration.js';
 export { DiscoveryError } from './error.js';
 export { hosted } from './hosted.js';

package/dist/release/legacy/index.d.ts

@@ -26,7 +26,10 @@
  * `protocol/invocation`, `protocol/routes` and `protocol/schema/installation/introspection` no
  * longer import this folder (`protocol/invocation/legacy/` and `protocol/routes/legacy/` go under
  * their own headers), and the version-1 branch of the Delivery v2 `acceptRequest`, which then
- * returns only its own `Request`.
+ * returns only its own `Request`. The installed listing's legacy pin goes with the folder: the
+ * `legacy` variant of `InstalledPin` and its `installedPin` branch in
+ * `protocol/schema/installation/introspection/codec.ts`, with the `publication` branch of
+ * `runtime/schema/installation/source/document.ts` `installedPin` that produces it.
  *
  * The frozen v3 projection of a `DomainRelease` (`projection.ts`, served at `domain.json` by v4
  * deployments) and its golden vectors have their own, later deletion condition: no pre-v4 Kernel

package/dist/routes/credential.d.ts

@@ -5,4 +5,15 @@ export declare function firstCredentialIsAmbient(entry: Route): boolean;
 export declare function specificHeaderWires(entry: Route): ReadonlySet<string>;
 export declare function putCredential(entry: Route, url: URL, headers: Record<string, string>, credential: string): void;
 export declare function withoutCredentialHeaders(entry: Route, input: Readonly<Record<string, string>>): Record<string, string>;
+/** A credential value together with the request channel that actually carried it. */
+export interface LocatedCredential {
+    readonly value: string;
+    readonly in: SingleCredentialSource['in'];
+}
 export declare function readCredential(entry: Route, url: URL, headers: Record<string, string>): string | undefined;
+/**
+ * Read the request credential and report which declared channel supplied it. A `cookie` channel is
+ * ambient (the browser attaches it automatically), which the Server uses to decide CSRF defense; a
+ * `header` (Bearer) or `query` channel is caller-chosen and not CSRF-exposed.
+ */
+export declare function locateCredential(entry: Route, url: URL, headers: Record<string, string>): LocatedCredential | undefined;

package/dist/routes/credential.js

@@ -52,7 +52,14 @@ export function withoutCredentialHeaders(entry, input) {
     return output;
 }
 export function readCredential(entry, url, headers) {
-    const found = [];
+    return locateCredential(entry, url, headers)?.value;
+}
+/**
+ * Read the request credential and report which declared channel supplied it. A `cookie` channel is
+ * ambient (the browser attaches it automatically), which the Server uses to decide CSRF defense; a
+ * `header` (Bearer) or `query` channel is caller-chosen and not CSRF-exposed.
+ */
+export function locateCredential(entry, url, headers) {
     if (entry.credential === undefined) {
         const authorization = headers.authorization;
         if (authorization === undefined)
@@ -60,8 +67,9 @@ export function readCredential(entry, url, headers) {
         const matched = /^Bearer[ \t]+([^\s]+)$/iu.exec(authorization.trim());
         if (matched === null)
             invalidRequest('Authorization must contain one Bearer credential.');
-        return matched[1];
+        return { value: matched[1], in: 'header' };
     }
+    const found = [];
     for (const source of credentialSources(entry)) {
         let value;
         if (source.in === 'header') {
@@ -78,7 +86,7 @@ export function readCredential(entry, url, headers) {
             value = cookie(headers.cookie, source.name);
         }
         if (value !== undefined)
-            found.push(value);
+            found.push({ value, in: source.in });
     }
     if (found.length > 1)
         invalidRequest('Request supplies more than one Astrale credential channel.');

package/dist/routes/decode.js

@@ -1,6 +1,6 @@
 import { NodePath } from '@astrale-os/kernel-core/path';
 import * as portable from '@astrale-os/kernel-dsl/value';
-import { readCredential, specificHeaderWires, withoutCredentialHeaders } from './credential.js';
+import { locateCredential, specificHeaderWires, withoutCredentialHeaders } from './credential.js';
 import { fail, invalidRequest } from './error.js';
 import { isReservedHeader } from './mapping.js';
 import { methodMatches } from './match.js';
@@ -44,7 +44,8 @@ export function decodeInvocation(entry, request, domain, routing) {
         throw cause;
     }
     const headers = normalizeHeaders(request.headers);
-    const credential = readCredential(entry, url, headers);
+    const located = locateCredential(entry, url, headers);
+    const credential = located?.value;
     const routed = routing(request);
     const applicationHeaders = withoutCredentialHeaders(entry, headers);
     for (const [name, wire] of Object.entries(entry.query ?? {})) {
@@ -130,6 +131,7 @@ export function decodeInvocation(entry, request, domain, routing) {
     return Object.freeze({
         call: Object.freeze({ target, input }),
         ...(credential === undefined ? {} : { credential }),
+        ...(located === undefined ? {} : { credentialIn: located.in }),
         ...(routed === undefined ? {} : { routing: routed }),
     });
 }

package/dist/routes/request.d.ts

@@ -5,6 +5,8 @@ import type { HttpMethod } from '../release/route.js';
 export interface Invocation {
     readonly call: Call;
     readonly credential?: string;
+    /** The request channel that carried `credential`; `cookie` is ambient (CSRF-exposed). */
+    readonly credentialIn?: 'header' | 'cookie' | 'query';
     readonly routing?: Via | PublicationVia;
     readonly method?: Exclude<HttpMethod, '*'>;
 }

package/dist/schema/installation/introspection/codec.d.ts

@@ -1,5 +1,5 @@
 import type { introspection } from '@astrale-os/kernel-core/schema';
-import type { DomainBundle, DomainDependencies, DomainInfo, Limits, ResultFor } from './result.js';
+import type { DomainBundle, DomainDependencies, DomainInfo, InstalledRelease, Limits, ResultFor } from './result.js';
 export declare const MEDIA_TYPE: 'application/vnd.astrale.schema-introspection.v3+json';
 export declare function encode<Input extends introspection.Introspection>(input: Input, result: ResultFor<Input>): Promise<Uint8Array>;
 export declare function decode<Input extends introspection.Introspection>(input: Input, bytes: Uint8Array, limits: Limits): Promise<ResultFor<Input>>;
@@ -7,7 +7,7 @@ export declare function decode<Input extends introspection.Introspection>(input:
  * Package-private: admit one decoded evidence value for an admitted request. Shared with the
  * pre-R1 representation in `../legacy/`, which decodes other bytes into this same wire value.
  */
-export declare function acceptEvidence(request: introspection.Introspection, decoded: unknown, limits: Limits): DomainInfo | DomainBundle | DomainDependencies;
+export declare function acceptEvidence(request: introspection.Introspection, decoded: unknown, limits: Limits): DomainInfo | DomainBundle | DomainDependencies | readonly InstalledRelease[];
 /** Package-private: admit the evidence bounds a request declares. Shared with `../legacy/`. */
 export declare function admitLimits(request: introspection.Introspection, limits: Limits): void;
 /** Admit dependency bindings: origin-ordered, one per origin, each label agreeing with its revisions. */

package/dist/schema/installation/introspection/codec.js

@@ -1,3 +1,4 @@
+import { is as isIssuer } from '@astrale-os/kernel-core/auth/issuer';
 import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
 import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
 import { revision as schemaRevision } from '@astrale-os/kernel-dsl/v1/schema/revision';
@@ -19,12 +20,16 @@ const ENCODE_LIMITS = Object.freeze({
 });
 export async function encode(input, result) {
     const request = admitRequest(input);
-    const wire = request.kind === 'bundle'
-        ? encodeDomainBundle(result)
-        : request.kind === 'dependencies'
-            ? encodeDomainDependencies(result)
-            : encodeDomainInfo(result);
-    proveRequestedOrigin(request, result);
+    const wire = request.kind === 'installed'
+        ? acceptInstalledReleases(result)
+        : request.kind === 'bundle'
+            ? encodeDomainBundle(result)
+            : request.kind === 'dependencies'
+                ? encodeDomainDependencies(result)
+                : encodeDomainInfo(result);
+    if (request.kind !== 'installed') {
+        proveRequestedOrigin(request, result);
+    }
     return encoder.encode(json.serialize(wire, { limits: ENCODE_LIMITS }));
 }
 export async function decode(input, bytes, limits) {
@@ -57,6 +62,8 @@ export async function decode(input, bytes, limits) {
  * pre-R1 representation in `../legacy/`, which decodes other bytes into this same wire value.
  */
 export function acceptEvidence(request, decoded, limits) {
+    if (request.kind === 'installed')
+        return acceptInstalledReleases(decoded);
     const result = request.kind === 'bundle'
         ? decodeDomainBundle(decoded, limits.maximumBundleBytes)
         : request.kind === 'dependencies'
@@ -125,6 +132,114 @@ function acceptDependencyBinding(input) {
         binding: expected,
     });
 }
+/** Admit the installed listing: origin-ordered, one release per origin, each pin of one kind. */
+function acceptInstalledReleases(input) {
+    if (!Array.isArray(input))
+        invalid('Installed releases are invalid.');
+    const releases = input.map(acceptInstalledRelease);
+    for (const [index, installed] of releases.entries()) {
+        const previous = releases[index - 1];
+        if (previous !== undefined && previous.origin >= installed.origin) {
+            invalid('Installed releases must be origin-ordered and unique.');
+        }
+    }
+    return Object.freeze(releases);
+}
+function acceptInstalledRelease(input) {
+    const value = record(input, 'Installed release');
+    exact(value, ['inFlight', 'issuer', 'origin', 'pin', 'revision', 'url'], 'Installed release');
+    if (typeof value.origin !== 'string' || !patterns.origin.test(value.origin)) {
+        invalid('Installed release origin is invalid.');
+    }
+    if (typeof value.revision !== 'string' || !patterns.revision.test(value.revision)) {
+        invalid('Installed release revision is invalid.');
+    }
+    const issuer = issuerId(value.issuer, 'Installed release issuer');
+    return Object.freeze({
+        origin: value.origin,
+        revision: value.revision,
+        issuer,
+        url: deploymentUrl(value.url),
+        pin: installedPin(value.pin),
+        inFlight: inFlightIssuers(value.inFlight, issuer),
+    });
+}
+function installedPin(input) {
+    const value = record(input, 'Installed pin');
+    if (value.kind === 'release') {
+        exact(value, ['build', 'kind', 'release'], 'Installed release pin');
+        return Object.freeze({
+            kind: 'release',
+            release: digest(value.release, 'Installed release'),
+            build: digest(value.build, 'Installed build'),
+        });
+    }
+    // Deprecated legacy v2/v3 pin: deleted with the `legacy` variant of `InstalledPin`, in the
+    // breaking release that deletes `runtime/schema/installation/source/legacy/`.
+    if (value.kind === 'legacy') {
+        exact(value, ['document', 'etag', 'kind'], 'Installed legacy pin');
+        if (value.document !== 2 && value.document !== 3) {
+            invalid('Installed legacy pin document version is invalid.');
+        }
+        return Object.freeze({
+            kind: 'legacy',
+            document: value.document,
+            etag: digest(value.etag, 'Installed legacy Publication'),
+        });
+    }
+    return invalid('Installed pin kind is invalid.');
+}
+function inFlightIssuers(input, current) {
+    if (!Array.isArray(input))
+        invalid('Installed release in-flight issuers are invalid.');
+    const entries = input.map((entry) => {
+        const value = record(entry, 'In-flight issuer');
+        exact(value, ['issuer', 'release', 'replacedAt'], 'In-flight issuer');
+        if (typeof value.replacedAt !== 'string' || !isInstant(value.replacedAt)) {
+            invalid('In-flight issuer replacement instant is invalid.');
+        }
+        return Object.freeze({
+            issuer: issuerId(value.issuer, 'In-flight issuer'),
+            release: digest(value.release, 'In-flight release'),
+            replacedAt: value.replacedAt,
+        });
+    });
+    for (const [index, entry] of entries.entries()) {
+        if (entry.issuer === current)
+            invalid('An in-flight issuer cannot be the current issuer.');
+        const previous = entries[index - 1];
+        if (previous !== undefined && previous.issuer >= entry.issuer) {
+            invalid('In-flight issuers must be issuer-ordered and unique.');
+        }
+    }
+    return Object.freeze(entries);
+}
+function issuerId(input, label) {
+    if (!isIssuer(input))
+        invalid(`${label} is invalid.`);
+    return input;
+}
+/** An HTTP(S) origin, spelled exactly as `URL.origin` spells it. */
+function deploymentUrl(input) {
+    let url;
+    try {
+        url = typeof input === 'string' ? new URL(input) : undefined;
+    }
+    catch {
+        url = undefined;
+    }
+    if (url === undefined || (url.protocol !== 'https:' && url.protocol !== 'http:')) {
+        invalid('Installed release URL is invalid.');
+    }
+    if (url.origin !== input)
+        invalid('Installed release URL must be an origin.');
+    return url.origin;
+}
+/** A UTC millisecond instant, spelled exactly as `Date.prototype.toISOString` spells it. */
+function isInstant(input) {
+    const time = Date.parse(input);
+    return Number.isFinite(time) && new Date(time).toISOString() === input;
+}
 function encodeDomainBundle(input) {
     exact(input, ['bundle', 'domain'], 'Domain Bundle result');
     const admittedDomain = acceptDomainInfo(input.domain);
@@ -238,6 +353,10 @@ function capabilities(input) {
 /** Package-private: admit one introspection request. Shared with `../legacy/`. */
 export function admitRequest(input) {
     const value = record(input, 'Schema introspection request');
+    if (value.kind === 'installed') {
+        exact(value, ['kind'], 'Schema introspection request');
+        return Object.freeze({ kind: 'installed' });
+    }
     exact(value, ['kind', 'origin'], 'Schema introspection request');
     if (value.kind !== 'inspect' && value.kind !== 'bundle' && value.kind !== 'dependencies') {
         invalid('Schema introspection kind is invalid.');

package/dist/schema/installation/introspection/index.d.ts

@@ -1,2 +1,2 @@
 export { MEDIA_TYPE, acceptDomainDependencies, acceptDomainInfo, decode, encode } from './codec.js';
-export type { DependencyBinding, Digest, DomainBundle, DomainDependencies, DomainInfo, Limits, ResultFor, } from './result.js';
+export type { DependencyBinding, Digest, DomainBundle, DomainDependencies, DomainInfo, InFlightIssuer, InstalledPin, InstalledRelease, Limits, ResultFor, } from './result.js';

package/dist/schema/installation/introspection/result.d.ts

@@ -1,5 +1,7 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { introspection } from '@astrale-os/kernel-core/schema';
 import type { bundle, Key, Revision } from '@astrale-os/kernel-dsl/v1';
+import type { BuildDigest, ReleaseDigest } from '../../../release/index.js';
 import type { Publication, PublicationRef, PublicationRequirements } from '../../../release/legacy/index.js';
 export type Digest = `sha256:${string}`;
 /** Lightweight proof of one exact ready installed Domain generation. */
@@ -43,7 +45,57 @@ export interface DomainDependencies {
     readonly domain: DomainInfo;
     readonly dependencies: readonly DependencyBinding[];
 }
+/**
+ * What one installation pins, one meaning per variant: a `DomainRelease` v4 by its release digest
+ * beside the build digest it runs, or a legacy v2/v3 Publication by its strong ETag.
+ */
+export type InstalledPin = ReleasePin | LegacyPin;
+/** A `DomainRelease` v4 pin: its release digest beside the build digest it runs. */
+interface ReleasePin {
+    readonly kind: 'release';
+    readonly release: ReleaseDigest;
+    readonly build: BuildDigest;
+}
+/**
+ * A legacy v2/v3 Publication pin: its document version and strong ETag.
+ *
+ * @deprecated Successor: the `release` pin. Short-term consumer: the installations that still pin
+ * a v2/v3 Publication, such as the astrale Host's v3 installs until Shell is republished as a
+ * release. Deleted, with its codec branch, in the separate breaking release that deletes
+ * `runtime/schema/installation/source/legacy/`, once no installation pins a v2/v3 Publication
+ * (the conditions of `protocol/release/legacy/index.ts`).
+ */
+interface LegacyPin {
+    readonly kind: 'legacy';
+    readonly document: 2 | 3;
+    readonly etag: Digest;
+}
+/**
+ * The issuer of a release one installation replaced, as the Kernel records it: accepted while its
+ * work drains, and listed until a later consented install re-pins or prunes it, drained or not.
+ */
+export interface InFlightIssuer {
+    readonly issuer: IssuerId;
+    /** Pinned document digest of the replaced release. */
+    readonly release: Digest;
+    /** UTC millisecond ISO 8601 instant of the activation commit that replaced it. */
+    readonly replacedAt: string;
+}
+/** One ready installation the Kernel pins to a deployment, as its caller can read it. */
+export interface InstalledRelease {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+    /** Issuer of the installation's Domain principal. */
+    readonly issuer: IssuerId;
+    /** The deployment URL, an HTTP(S) origin, the Kernel discovered the pinned document at. */
+    readonly url: string;
+    readonly pin: InstalledPin;
+    /** Issuer-ordered, distinct, never the current issuer. */
+    readonly inFlight: readonly InFlightIssuer[];
+}
 export type ResultFor<Input extends introspection.Introspection> = Input extends {
+    readonly kind: 'installed';
+} ? readonly InstalledRelease[] : Input extends {
     readonly kind: 'bundle';
 } ? DomainBundle : Input extends {
     readonly kind: 'dependencies';
@@ -52,3 +104,4 @@ export interface Limits {
     readonly maximumPublicationBytes: number;
     readonly maximumBundleBytes: number;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-protocol",
-  "version": "0.5.0-beta.68",
+  "version": "0.5.0-beta.69",
   "description": "Portable Astrale invocation, publication, installation, routing, and issuer protocols",
   "license": "Apache-2.0",
   "repository": {
@@ -27,6 +27,10 @@
       "types": "./dist/errors/index.d.ts",
       "import": "./dist/errors/index.js"
     },
+    "./issuer/claims": {
+      "types": "./dist/issuer/claims.d.ts",
+      "import": "./dist/issuer/claims.js"
+    },
     "./issuer/configuration": {
       "types": "./dist/issuer/configuration.d.ts",
       "import": "./dist/issuer/configuration.js"
@@ -169,8 +173,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.62",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.44",
+    "@astrale-os/kernel-core": "0.9.0-beta.63",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.45",
     "@noble/hashes": "2.3.0"
   },
   "devDependencies": {