@astrale-os/kernel-server 0.4.17 → 0.5.0-beta.10

package/dist/issuer/exchange.js

@@ -0,0 +1,136 @@
+import { inspect as inspectCredential } from '@astrale-os/kernel-core/auth/credential';
+import * as errors from '@astrale-os/kernel-protocol/errors';
+import * as exchangeProtocol from '@astrale-os/kernel-protocol/issuer/exchange';
+import { paths as issuerPaths } from '@astrale-os/kernel-protocol/issuer/paths';
+const PROVIDER_CODES = new Set([
+    errors.CODES.AUTH_INVALID,
+    errors.CODES.AUTH_EXPIRED,
+    errors.CODES.BACKEND_UNAVAILABLE,
+    errors.CODES.DEADLINE_EXCEEDED,
+]);
+export function capture(input) {
+    if (input === null || typeof input !== 'object' || typeof input.exchange !== 'function') {
+        throw new TypeError('Token-exchange provider is invalid.');
+    }
+    const exchange = input.exchange;
+    return Object.freeze({
+        exchange: (request, context) => exchange.call(input, request, context),
+    });
+}
+export function mount(app, issuer, provider, cors, active, timeoutMs) {
+    const path = issuerPaths(issuer).tokenExchange;
+    if (cors.enabled) {
+        app.options(path, (context) => cors.preflight(context.req.raw, { methods: ['POST'], headers: ['authorization', 'accept'] }));
+    }
+    app.all(path, async (context) => {
+        const request = context.req.raw;
+        const respond = (payload, extra) => json(payload, errors.httpStatusOf(payload.error), request, cors, extra);
+        let admitted;
+        try {
+            admitted = exchangeProtocol.acceptHttpRequest({
+                method: request.method,
+                url: request.url,
+                authorization: request.headers.get('authorization'),
+                accept: request.headers.get('accept'),
+            });
+        }
+        catch (cause) {
+            if (cause instanceof errors.ProtocolError) {
+                return respond(exchangeProtocol.acceptErrorResponse({ error: cause.payload }), cause.payload.code === errors.CODES.METHOD_NOT_ALLOWED ? { allow: 'POST' } : undefined);
+            }
+            throw cause;
+        }
+        if (!active.isAccepting) {
+            return respond(error('BACKEND_UNAVAILABLE', 'Token exchange is unavailable.'));
+        }
+        const operation = active.begin(timeoutMs, request.signal);
+        if (operation === undefined) {
+            return respond(error('LIMIT_EXCEEDED', 'Token-exchange limit exceeded.'));
+        }
+        try {
+            try {
+                await requireEmptyBody(request, operation.signal);
+            }
+            catch (cause) {
+                if (operation.timedOut) {
+                    return respond(error('DEADLINE_EXCEEDED', 'Token-exchange deadline elapsed.'));
+                }
+                if (cause instanceof errors.ProtocolError) {
+                    return respond(exchangeProtocol.acceptErrorResponse({ error: cause.payload }));
+                }
+                throw cause;
+            }
+            let output;
+            try {
+                output = await provider.exchange(admitted, { signal: operation.signal });
+            }
+            catch (cause) {
+                if (operation.timedOut) {
+                    return respond(error('DEADLINE_EXCEEDED', 'Token-exchange deadline elapsed.'));
+                }
+                if (cause instanceof errors.ProtocolError && PROVIDER_CODES.has(cause.payload.code)) {
+                    return respond(exchangeProtocol.acceptErrorResponse({ error: cause.payload }));
+                }
+                throw cause;
+            }
+            if (operation.timedOut) {
+                return respond(error('DEADLINE_EXCEEDED', 'Token-exchange deadline elapsed.'));
+            }
+            const response = exchangeProtocol.acceptResponse(output);
+            if (inspectCredential(response.token).claims.exp !== response.expiresAt) {
+                throw new TypeError('Token-exchange provider returned inconsistent expiry evidence.');
+            }
+            return json(response, 200, request, cors);
+        }
+        catch {
+            return respond(error('INTERNAL_ERROR', 'Internal token-exchange failure.'));
+        }
+        finally {
+            operation.settle();
+        }
+    });
+}
+async function requireEmptyBody(request, signal) {
+    const declared = request.headers.get('content-length');
+    if (declared !== null && declared !== '0')
+        invalidRequest();
+    const reader = request.body?.getReader();
+    if (reader === undefined)
+        return;
+    const abort = () => void reader.cancel(signal.reason).catch(() => undefined);
+    signal.addEventListener('abort', abort, { once: true });
+    try {
+        if (signal.aborted)
+            throw signal.reason;
+        const first = await reader.read();
+        if (!first.done) {
+            await reader.cancel('token exchange requires an empty body').catch(() => undefined);
+            invalidRequest();
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        reader.releaseLock();
+    }
+}
+function invalidRequest() {
+    throw new errors.ProtocolError({
+        code: errors.CODES.INVALID_REQUEST,
+        message: 'Token exchange requires an empty request body.',
+    });
+}
+function error(code, message) {
+    return exchangeProtocol.acceptErrorResponse({
+        error: { code: errors.CODES[code], message },
+    });
+}
+function json(value, status, request, cors, extra) {
+    const headers = new Headers(exchangeProtocol.responseHeaders());
+    for (const [name, value] of Object.entries(cors.response(request)))
+        headers.set(name, value);
+    if (extra !== undefined) {
+        for (const [name, value] of new Headers(extra))
+            headers.set(name, value);
+    }
+    return new Response(JSON.stringify(value), { status, headers });
+}

package/dist/issuer/index.d.ts

@@ -0,0 +1,3 @@
+export { admitIssuer, issuerRouteReservations, mountIssuer, type IssuerRouteReservation, } from './routes.js';
+export type * as exchange from './exchange.js';
+export type { Issuer } from './types.js';

package/dist/issuer/index.js

@@ -0,0 +1 @@
+export { admitIssuer, issuerRouteReservations, mountIssuer, } from './routes.js';

package/dist/issuer/routes.d.ts

@@ -0,0 +1,13 @@
+import type { CorsPolicy } from '../cors/index.js';
+import type { ActiveOperations } from '../lifecycle/index.js';
+import type { ServerRouter } from '../transport/index.js';
+import type { Provider } from './exchange.js';
+import type { Issuer } from './types.js';
+export interface IssuerRouteReservation {
+    readonly path: string;
+    readonly methods: readonly string[];
+}
+export declare function issuerRouteReservations(input: Issuer, tokenExchange?: boolean): readonly IssuerRouteReservation[];
+export declare function mountIssuer(app: ServerRouter, input: Issuer, cors: CorsPolicy, active: ActiveOperations, timeoutMs: number, tokenExchange?: Provider): void;
+/** Admit static discovery configuration before Runtime Boot performs any durable work. */
+export declare function admitIssuer(input: Issuer): Issuer;

package/dist/issuer/routes.js

@@ -0,0 +1,149 @@
+import { configuration } from '@astrale-os/kernel-protocol/issuer/configuration';
+import { hosted } from '@astrale-os/kernel-protocol/issuer/hosted';
+import { keySet } from '@astrale-os/kernel-protocol/issuer/key-set';
+import { paths as issuerPaths } from '@astrale-os/kernel-protocol/issuer/paths';
+import { IssuerKeysUnavailableError } from '../errors/index.js';
+import { mount } from './exchange.js';
+export function issuerRouteReservations(input, tokenExchange = false) {
+    const paths = issuerPaths(input.issuer);
+    const reservations = [
+        Object.freeze({ path: paths.configuration, methods: Object.freeze(['GET']) }),
+        Object.freeze({ path: paths.keys, methods: Object.freeze(['GET']) }),
+    ];
+    if (tokenExchange) {
+        reservations.push(Object.freeze({ path: paths.tokenExchange, methods: Object.freeze(['POST']) }));
+    }
+    if (input.loadIssuerPublicKeys !== undefined) {
+        const base = new URL(input.issuer).pathname.replace(/\/+$/u, '');
+        reservations.push(Object.freeze({
+            path: `${base}/iss/{thumbprint}/.well-known/openid-configuration`,
+            methods: Object.freeze(['GET']),
+        }), Object.freeze({
+            path: `${base}/iss/{thumbprint}/.well-known/jwks.json`,
+            methods: Object.freeze(['GET']),
+        }));
+    }
+    return Object.freeze(reservations);
+}
+export function mountIssuer(app, input, cors, active, timeoutMs, tokenExchange) {
+    const issuer = input.issuer;
+    const paths = issuerPaths(issuer);
+    const headers = (request) => ({
+        ...cors.response(request),
+        'cache-control': 'no-cache',
+    });
+    const algorithm = input.signingAlgorithm ?? 'ES256';
+    const discovery = configuration(issuer, [algorithm], {
+        tokenExchange: tokenExchange !== undefined,
+    });
+    app.get(paths.configuration, (context) => context.json(discovery, 200, headers(context.req.raw)));
+    if (cors.enabled) {
+        app.options(paths.configuration, (context) => cors.preflight(context.req.raw, { methods: ['GET'] }));
+        app.options(paths.keys, (context) => cors.preflight(context.req.raw, { methods: ['GET'] }));
+    }
+    app.get(paths.keys, async (context) => {
+        const operation = active.begin(timeoutMs, context.req.raw.signal);
+        if (operation === undefined) {
+            return context.json({ error: 'Issuer is unavailable while draining.' }, 503, headers(context.req.raw));
+        }
+        try {
+            const keys = await input.loadPublicKeys(operation.signal);
+            return context.json(keySet(keys, [algorithm]), 200, headers(context.req.raw));
+        }
+        catch (cause) {
+            if (operation.signal.aborted || cause instanceof IssuerKeysUnavailableError) {
+                return context.json({ error: 'Issuer keys are unavailable.' }, 503, headers(context.req.raw));
+            }
+            throw cause;
+        }
+        finally {
+            operation.settle();
+        }
+    });
+    if (tokenExchange !== undefined) {
+        mount(app, issuer, tokenExchange, cors, active, timeoutMs);
+    }
+    const loadIssuerPublicKeys = input.loadIssuerPublicKeys;
+    if (loadIssuerPublicKeys !== undefined) {
+        const base = new URL(issuer).pathname.replace(/\/+$/, '');
+        if (cors.enabled) {
+            app.options(`${base}/iss/:thumbprint/.well-known/openid-configuration`, (context) => cors.preflight(context.req.raw, { methods: ['GET'] }));
+            app.options(`${base}/iss/:thumbprint/.well-known/jwks.json`, (context) => cors.preflight(context.req.raw, { methods: ['GET'] }));
+        }
+        app.get(`${base}/iss/:thumbprint/.well-known/openid-configuration`, async (context) => {
+            const hostedIssuer = hosted(issuer, context.req.param('thumbprint'));
+            if (hostedIssuer === undefined)
+                return context.json({ error: 'Issuer not found.' }, 404, headers(context.req.raw));
+            const operation = active.begin(timeoutMs, context.req.raw.signal);
+            if (operation === undefined) {
+                return context.json({ error: 'Issuer is unavailable while draining.' }, 503, headers(context.req.raw));
+            }
+            try {
+                const keys = await hostedKeys(loadIssuerPublicKeys, hostedIssuer, operation.signal, algorithm);
+                if (keys.length === 0)
+                    return context.json({ error: 'Issuer not found.' }, 404, headers(context.req.raw));
+                return context.json(configuration(hostedIssuer, [algorithm]), 200, headers(context.req.raw));
+            }
+            catch (cause) {
+                if (operation.signal.aborted || cause instanceof IssuerKeysUnavailableError) {
+                    return context.json({ error: 'Issuer keys are unavailable.' }, 503, headers(context.req.raw));
+                }
+                throw cause;
+            }
+            finally {
+                operation.settle();
+            }
+        });
+        app.get(`${base}/iss/:thumbprint/.well-known/jwks.json`, async (context) => {
+            const hostedIssuer = hosted(issuer, context.req.param('thumbprint'));
+            if (hostedIssuer === undefined)
+                return context.json({ error: 'Issuer not found.' }, 404, headers(context.req.raw));
+            const operation = active.begin(timeoutMs, context.req.raw.signal);
+            if (operation === undefined) {
+                return context.json({ error: 'Issuer is unavailable while draining.' }, 503, headers(context.req.raw));
+            }
+            try {
+                const keys = await hostedKeys(loadIssuerPublicKeys, hostedIssuer, operation.signal, algorithm);
+                if (keys.length === 0)
+                    return context.json({ error: 'Issuer not found.' }, 404, headers(context.req.raw));
+                return context.json({ keys }, 200, headers(context.req.raw));
+            }
+            catch (cause) {
+                if (operation.signal.aborted || cause instanceof IssuerKeysUnavailableError) {
+                    return context.json({ error: 'Issuer keys are unavailable.' }, 503, headers(context.req.raw));
+                }
+                throw cause;
+            }
+            finally {
+                operation.settle();
+            }
+        });
+    }
+}
+async function hostedKeys(load, issuer, signal, algorithm) {
+    return keySet(await load(issuer, signal), [algorithm]).keys;
+}
+/** Admit static discovery configuration before Runtime Boot performs any durable work. */
+export function admitIssuer(input) {
+    const signingAlgorithm = input.signingAlgorithm ?? 'ES256';
+    const issuer = configuration(input.issuer, [signingAlgorithm]).issuer;
+    if (typeof input.loadPublicKeys !== 'function') {
+        throw new TypeError('Issuer public-key loader is invalid.');
+    }
+    if (input.loadIssuerPublicKeys !== undefined &&
+        typeof input.loadIssuerPublicKeys !== 'function') {
+        throw new TypeError('Hosted issuer discovery loader is invalid.');
+    }
+    const loadPublicKeys = input.loadPublicKeys;
+    const loadIssuerPublicKeys = input.loadIssuerPublicKeys;
+    return Object.freeze({
+        issuer,
+        signingAlgorithm,
+        loadPublicKeys: (signal) => loadPublicKeys.call(input, signal),
+        ...(loadIssuerPublicKeys === undefined
+            ? {}
+            : {
+                loadIssuerPublicKeys: (hostedIssuer, signal) => loadIssuerPublicKeys.call(input, hostedIssuer, signal),
+            }),
+    });
+}

package/dist/issuer/types.d.ts

@@ -0,0 +1,11 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { JsonWebKey } from '@astrale-os/kernel-core/auth/jwk';
+/** Public issuer material; Server never receives private signing material. */
+export interface Issuer {
+    readonly issuer: IssuerId;
+    readonly signingAlgorithm?: string;
+    /** Bounded request-time read; cancellation is owned by Server. */
+    loadPublicKeys(signal: AbortSignal): Promise<readonly JsonWebKey[]>;
+    /** Optional hosted-key discovery for issuers below `<issuer>/iss/:thumbprint`. */
+    readonly loadIssuerPublicKeys?: (issuer: IssuerId, signal: AbortSignal) => Promise<readonly JsonWebKey[]>;
+}

package/dist/issuer/types.js

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

package/dist/lifecycle/active.d.ts

@@ -0,0 +1,39 @@
+type CancelWork = (reason: string) => void | Promise<void>;
+type BackgroundTask = () => void | PromiseLike<unknown>;
+/** Minimal close capability retained by Server lifecycle without importing transport. */
+export interface ActiveSocket {
+    close(code?: number, reason?: string): void;
+}
+/** One Server-owned operation from body admission through terminal result settlement. */
+export interface ActiveOperation {
+    readonly deadline: number;
+    readonly signal: AbortSignal;
+    readonly timedOut: boolean;
+    /** Register cooperative cleanup and return an idempotent unregistration function. */
+    onCancel(cancel: CancelWork): () => void;
+    cancel(reason: string): void;
+    settle(): void;
+    readonly finished: Promise<void>;
+}
+export declare class ActiveOperations {
+    private readonly maximumConcurrentOperations;
+    private accepting;
+    private closed;
+    private readonly operations;
+    private readonly sockets;
+    private readonly backgroundTasks;
+    private closing?;
+    private changed;
+    constructor(maximumConcurrentOperations: number);
+    get isAccepting(): boolean;
+    begin(timeoutMs: number, externalSignal?: AbortSignal): ActiveOperation | undefined;
+    attachSocket(socket: ActiveSocket): boolean;
+    detachSocket(socket: ActiveSocket): void;
+    background(task: BackgroundTask, retain?: (promise: Promise<unknown>) => void): void;
+    drain(): void;
+    close(deadline: number): Promise<void>;
+    private closeOnce;
+    private waitUntilIdleOr;
+    private closeSockets;
+}
+export {};

package/dist/lifecycle/active.js

@@ -0,0 +1,199 @@
+export class ActiveOperations {
+    maximumConcurrentOperations;
+    accepting = true;
+    closed = false;
+    operations = new Set();
+    sockets = new Set();
+    backgroundTasks = new Set();
+    closing;
+    changed;
+    constructor(maximumConcurrentOperations) {
+        this.maximumConcurrentOperations = maximumConcurrentOperations;
+    }
+    get isAccepting() {
+        return this.accepting;
+    }
+    begin(timeoutMs, externalSignal) {
+        if (!this.accepting || this.operations.size >= this.maximumConcurrentOperations) {
+            return undefined;
+        }
+        const operation = new Operation(Date.now() + timeoutMs, () => {
+            this.operations.delete(operation);
+            this.changed?.();
+        });
+        this.operations.add(operation);
+        operation.link(externalSignal);
+        return operation;
+    }
+    attachSocket(socket) {
+        if (!this.accepting)
+            return false;
+        this.sockets.add(socket);
+        return true;
+    }
+    detachSocket(socket) {
+        this.sockets.delete(socket);
+    }
+    background(task, retain) {
+        if (typeof task !== 'function')
+            throw new TypeError('Background task must be a function.');
+        if (this.closed)
+            throw new Error('Server is closed.');
+        const tracked = Promise.resolve()
+            .then(task)
+            .then(() => undefined, (cause) => {
+            // Background work has no response channel; report without creating an unhandled rejection.
+            // oxlint-disable-next-line no-console
+            console.error('[server] background task failed:', cause);
+        })
+            .finally(() => {
+            this.backgroundTasks.delete(tracked);
+            this.changed?.();
+        });
+        this.backgroundTasks.add(tracked);
+        try {
+            retain?.(tracked);
+        }
+        catch {
+            // Server retention remains authoritative when a platform bridge refuses the registration.
+        }
+    }
+    drain() {
+        this.accepting = false;
+    }
+    close(deadline) {
+        this.drain();
+        this.closing ??= this.closeOnce(deadline);
+        return this.closing;
+    }
+    async closeOnce(deadline) {
+        await this.waitUntilIdleOr(deadline);
+        if (this.operations.size > 0) {
+            for (const operation of this.operations)
+                operation.cancel('server closing');
+        }
+        this.closeSockets();
+        // Give cooperative cancellation and iterator returns one turn to settle. The absolute deadline
+        // has already elapsed; an uncooperative operation must reject close rather than pin Host forever.
+        await Promise.resolve();
+        if (this.operations.size > 0 || this.backgroundTasks.size > 0) {
+            this.closed = true;
+            throw new Error(`Server close deadline elapsed with ${this.operations.size} active operation(s) and ${this.backgroundTasks.size} background task(s).`);
+        }
+        this.closed = true;
+    }
+    async waitUntilIdleOr(deadline) {
+        while (this.operations.size > 0 || this.backgroundTasks.size > 0) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return;
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, Math.min(remaining, 2_147_483_647));
+                this.changed = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+            this.changed = undefined;
+        }
+    }
+    closeSockets() {
+        for (const socket of this.sockets) {
+            try {
+                socket.close(1012, 'Server restarting');
+            }
+            catch {
+                // The platform already owns a broken socket; no further work is possible.
+            }
+        }
+        this.sockets.clear();
+    }
+}
+class Operation {
+    deadline;
+    onSettled;
+    controller = new AbortController();
+    cancelWork = new Set();
+    timer;
+    external;
+    settled = false;
+    cancelled = false;
+    timeout = false;
+    resolveFinished;
+    finished;
+    constructor(deadline, onSettled) {
+        this.deadline = deadline;
+        this.onSettled = onSettled;
+        this.finished = new Promise((resolve) => {
+            this.resolveFinished = resolve;
+        });
+        this.timer = setTimeout(() => {
+            this.timeout = true;
+            this.cancel('invocation deadline exceeded');
+        }, Math.min(Math.max(0, deadline - Date.now()), 2_147_483_647));
+    }
+    link(signal) {
+        if (signal === undefined)
+            return;
+        const abort = () => this.cancel('transport disconnected');
+        this.external = [signal, abort];
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    get timedOut() {
+        return this.timeout;
+    }
+    onCancel(cancel) {
+        if (this.cancelled) {
+            void settleCancellation(cancel, abortReason(this.controller.signal));
+            return () => undefined;
+        }
+        this.cancelWork.add(cancel);
+        return () => {
+            this.cancelWork.delete(cancel);
+        };
+    }
+    cancel(reason) {
+        if (this.cancelled || this.settled)
+            return;
+        this.cancelled = true;
+        clearTimeout(this.timer);
+        this.detachExternal();
+        this.controller.abort(new Error(reason));
+        for (const cancel of this.cancelWork)
+            void settleCancellation(cancel, reason);
+        this.cancelWork.clear();
+    }
+    settle() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        clearTimeout(this.timer);
+        this.detachExternal();
+        this.cancelWork.clear();
+        this.onSettled();
+        this.resolveFinished();
+    }
+    detachExternal() {
+        if (this.external === undefined)
+            return;
+        this.external[0].removeEventListener('abort', this.external[1]);
+        this.external = undefined;
+    }
+}
+async function settleCancellation(cancel, reason) {
+    try {
+        await cancel(reason);
+    }
+    catch {
+        // Cancellation is best-effort; the owning operation still settles through its execution path.
+    }
+}
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason.message : 'operation cancelled';
+}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1 @@
+export { ActiveOperations, type ActiveOperation, type ActiveSocket } from './active.js';

package/dist/lifecycle/index.js

@@ -0,0 +1 @@
+export { ActiveOperations } from './active.js';

package/dist/publication/delivery/handler.d.ts

@@ -0,0 +1,9 @@
+import type { ActiveOperations } from '../../lifecycle/index.js';
+import type { PreparedPublicationSnapshot } from '../snapshot.js';
+import type { Provider } from './types.js';
+export interface Limits {
+    readonly maximumDeliveryBytes: number;
+    readonly invocationTimeoutMs: number;
+}
+/** Serve one delivery request against the exact Publication snapshot that selected its URL. */
+export declare function handleDelivery(request: Request, snapshot: PreparedPublicationSnapshot, provider: Provider | undefined, active: ActiveOperations, limits: Limits, cors: Readonly<Record<string, string>>): Promise<Response>;