@astrale-os/kernel-client 0.6.0-beta.70 → 0.6.0-beta.71

package/dist/auth/auth.d.ts

@@ -1,13 +1,25 @@
-import type { Identity, Authentication, IdentityId, MintedCredential, RegisterResult } from '@astrale-os/kernel-core/auth';
-import type { PathLike } from '@astrale-os/kernel-core/path';
-import type { Input } from '../client/index.js';
+import type { Identity, Authentication, IdentityId, MintedCredential, RegisterResult, UnresolvedIdentityExpr } from '@astrale-os/kernel-core/auth';
+import type { NodePath, PathLike } from '@astrale-os/kernel-core/path';
+import type { Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { Call, Input } from '../client/index.js';
 import type { RequestOptions } from '../transport/index.js';
 import type { PolicyDecisionInput } from './authorization.js';
 import type { DelegateOptions, MintOptions, ImpersonateOptions } from './credential.js';
 import type { WhoisInput } from './identity.js';
 import type { RegisterRequest } from './register.js';
 export type AuthCall = (target: PathLike, input: Input, options?: RequestOptions) => Promise<Input>;
+/** Current admission of one remote Call; the target has not been executed. */
+export interface FunctionAdmission {
+    readonly callable: Key.Callable;
+    readonly receiver?: NodePath;
+}
+export interface AdmissionOptions extends RequestOptions {
+    /** Intersect the caller's Grant; defaults to explicit session attenuation, then self. */
+    readonly attenuation?: UnresolvedIdentityExpr;
+}
 export interface AuthApi {
+    /** Check access and input without executing an installed remote callable. */
+    admit(call: Call, options?: AdmissionOptions): Promise<FunctionAdmission>;
     register(input: RegisterRequest, options?: RequestOptions): Promise<RegisterResult>;
     whoami(options?: RequestOptions): Promise<Identity & Authentication>;
     whois(input: WhoisInput, options?: RequestOptions): Promise<(Identity & Authentication) | null>;
@@ -18,5 +30,5 @@ export interface AuthApi {
     mint(input: MintOptions, options?: RequestOptions): Promise<MintedCredential>;
     delegate(identity: IdentityId, input: DelegateOptions, options?: RequestOptions): Promise<MintedCredential>;
 }
-/** Bind the current Core identity syscalls without recreating legacy grant-edge verbs. */
-export declare function createAuth(call: AuthCall): AuthApi;
+/** Internal composition over callbacks owned by the Session or its bound view. */
+export declare function createAuth(call: AuthCall, admit: AuthApi['admit']): AuthApi;

package/dist/auth/auth.js

@@ -2,11 +2,10 @@ import { authorizationApi } from './authorization.js';
 import { credentialApi } from './credential.js';
 import { identityApi } from './identity.js';
 import { registerApi } from './register.js';
-/** Bind the current Core identity syscalls without recreating legacy grant-edge verbs. */
-export function createAuth(call) {
-    if (typeof call !== 'function')
-        throw new TypeError('Auth call capability is invalid.');
+/** Internal composition over callbacks owned by the Session or its bound view. */
+export function createAuth(call, admit) {
     return Object.freeze({
+        admit,
         ...registerApi(call),
         ...identityApi(call),
         ...authorizationApi(call),

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-export { createAuth, type AuthApi, type AuthCall } from './auth.js';
+export type { AuthApi, AdmissionOptions, FunctionAdmission } from './auth.js';
 export { IDENTITY_CAN_PATH, type PolicyDecisionInput } from './authorization.js';
 export { IDENTITY_MINT_PATH, IDENTITY_IMPERSONATE_PATH, type DelegateOptions, type MintOptions, type ImpersonateOptions, } from './credential.js';
 export { IDENTITY_WHOAMI_PATH, IDENTITY_WHOIS_PATH, type WhoisInput } from './identity.js';

package/dist/auth/index.js

@@ -1,4 +1,3 @@
-export { createAuth } from './auth.js';
 export { IDENTITY_CAN_PATH } from './authorization.js';
 export { IDENTITY_MINT_PATH, IDENTITY_IMPERSONATE_PATH, } from './credential.js';
 export { IDENTITY_WHOAMI_PATH, IDENTITY_WHOIS_PATH } from './identity.js';

package/dist/session/admission.d.ts

@@ -0,0 +1,18 @@
+import type { invocation } from '@astrale-os/kernel-protocol';
+import type { AdmissionOptions, FunctionAdmission } from '../auth/index.js';
+import type { Client } from '../client/index.js';
+import type { SchemaOptions } from '../schema/schema.js';
+import type { Fetch } from '../transport/http/index.js';
+import type { SessionOperation, SessionPolicy } from './context/index.js';
+import type { SessionAuth } from './routing/index.js';
+export interface FunctionAdmissionDependencies {
+    readonly kernel: string;
+    readonly auth?: SessionAuth;
+    readonly source: () => Client;
+    readonly fetch: Fetch;
+    readonly policy: Readonly<SessionPolicy>;
+    readonly limits: SchemaOptions;
+    readonly maximumResponseBytes: number;
+}
+/** Check a remote Call through the existing Domain exchange and Kernel admission protocols. */
+export declare function admitFunction(dependencies: FunctionAdmissionDependencies, call: invocation.Call, options: AdmissionOptions | undefined, operation: SessionOperation): Promise<FunctionAdmission>;

package/dist/session/admission.js

@@ -0,0 +1,117 @@
+import { grant } from '@astrale-os/kernel-core/auth';
+import { targetPath } from '@astrale-os/kernel-core/callable';
+import { Path } from '@astrale-os/kernel-core/path';
+import { admitOutput } from '@astrale-os/kernel-core/schema/kernel/syscalls/contracts';
+import { function as functions } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { codecs, issuer } from '@astrale-os/kernel-protocol';
+import { credentialApi } from '../auth/credential.js';
+import { identityApi } from '../auth/identity.js';
+import { ClientError } from '../errors/index.js';
+import { createSchema } from '../schema/index.js';
+import { allowEndpoint, runSessionOperation, sessionTransportOptions } from './context/index.js';
+import { boundedResponse, requireExactResponse } from './discovery/index.js';
+import { matchesCallable } from './reference.js';
+import { requireResultKind, resolveAuth } from './routing/index.js';
+const ADMIT = Path.staticMethod(Path.project(functions.admit.owner), functions.admit.name);
+/** Check a remote Call through the existing Domain exchange and Kernel admission protocols. */
+export async function admitFunction(dependencies, call, options, operation) {
+    const target = Path.parse(targetPath(call.target));
+    const origin = callableOrigin(target);
+    const attenuation = options?.attenuation === undefined
+        ? undefined
+        : grant.acceptUnresolved({ v: 1, expr: options.attenuation }).expr;
+    const effective = await resolveAuth(dependencies.auth, call, operation);
+    if (effective.credential === undefined || effective.delegate === undefined) {
+        throw new ClientError('Function admission requires an authenticated session.');
+    }
+    // Resolve once for the intended Call, then retain that exact caller across every helper syscall.
+    const client = dependencies.source();
+    const caller = client.as(effective.credential);
+    const dispatch = (input) => runSessionOperation(operation, () => caller.dispatch(input, {
+        ...sessionTransportOptions(operation),
+        delegate: effective.delegate,
+    }));
+    const callIdentity = async (target, input) => requireResultKind('value', await dispatch({ target, input })).value;
+    const identity = identityApi(callIdentity);
+    const credentials = credentialApi(callIdentity);
+    const schema = createSchema(dispatch, dependencies.limits);
+    const [domain, self] = await Promise.all([schema.inspect(origin), identity.whoami()]);
+    const remote = domain.publication;
+    if (remote === null || remote.identity.issuer === dependencies.kernel) {
+        throw new ClientError('Function admission through token exchange requires a remote Domain.');
+    }
+    const configuration = issuer.acceptConfiguration(await fetchJson(dependencies, new URL(issuer.paths(remote.identity.issuer).configuration, remote.identity.issuer).href, operation), remote.identity.issuer);
+    const endpoint = configuration.token_exchange_endpoint;
+    if (endpoint === undefined) {
+        throw new ClientError('The installed Domain does not advertise token exchange.');
+    }
+    allowEndpoint(endpoint, dependencies.policy);
+    const credential = await credentials.delegate(self.id, {
+        audience: remote.identity.issuer,
+        ttlSeconds: effective.delegate.ttlSeconds,
+        attenuation: attenuation ?? effective.delegate.attenuation ?? { kind: 'identity', self: true },
+    });
+    const exchanged = issuer.exchange.acceptResponse(await fetchJson(dependencies, endpoint, operation, credential));
+    if (exchanged.expiresAt * 1_000 <= Date.now()) {
+        throw new ClientError('Domain token exchange returned an expired credential.');
+    }
+    const result = await runSessionOperation(operation, () => client
+        .as(exchanged.token)
+        .dispatch({ target: ADMIT, input: { call, credential } }, { ...sessionTransportOptions(operation), delegate: effective.delegate }));
+    const output = admitOutput.parse(requireResultKind('value', result).value);
+    const callable = Key(output.callable);
+    if (!matchesCallable(target, callable)) {
+        throw new ClientError('Function admission returned a different callable.');
+    }
+    const receiver = output.receiver === undefined ? undefined : Path.parse(output.receiver);
+    const method = target.ast.steps.at(-1);
+    const instance = method?.kind === 'method' && method.dispatch === 'instance';
+    if (instance !== (receiver !== undefined) ||
+        (receiver !== undefined &&
+            (receiver.ast.anchor.kind !== 'id' ||
+                receiver.ast.steps.length !== 0 ||
+                (target.ast.anchor.kind === 'id' &&
+                    target.ast.steps.length === 1 &&
+                    receiver.ast.anchor.id !== target.ast.anchor.id)))) {
+        throw new ClientError('Function admission returned a different receiver.');
+    }
+    return Object.freeze({ callable, ...(receiver === undefined ? {} : { receiver: receiver.raw }) });
+}
+function callableOrigin(path) {
+    const last = path.ast.steps.at(-1);
+    if (last?.kind === 'method' && last.dispatch === 'instance')
+        return Key.origin(last.class);
+    if (path.ast.anchor.kind === 'domain')
+        return path.ast.anchor.origin;
+    throw new ClientError('Function admission requires a Domain-qualified callable target.');
+}
+async function fetchJson(dependencies, url, operation, credential) {
+    allowEndpoint(url, dependencies.policy);
+    return runSessionOperation(operation, async (signal) => {
+        const init = {
+            method: credential === undefined ? 'GET' : 'POST',
+            headers: {
+                accept: 'application/json',
+                ...(credential === undefined ? {} : { authorization: `Bearer ${credential}` }),
+            },
+            credentials: 'omit',
+            cache: 'no-store',
+            referrerPolicy: 'no-referrer',
+            redirect: 'manual',
+            signal,
+        };
+        const response = await dependencies.fetch(url, init);
+        try {
+            requireExactResponse(response, url, 'Domain token exchange');
+            if (!response.ok) {
+                throw new ClientError(`Domain ${credential === undefined ? 'discovery' : 'token exchange'} returned HTTP ${response.status}.`);
+            }
+            return codecs.json.decode(await boundedResponse(response, dependencies.maximumResponseBytes, signal));
+        }
+        finally {
+            // Also release unread bodies rejected by URL, status, or declared-size validation.
+            void response.body?.cancel().catch(() => undefined);
+        }
+    });
+}

package/dist/session/bound.d.ts

@@ -1,17 +1,18 @@
 import type { IssuerId } from '@astrale-os/kernel-core/auth';
+import type { AuthApi } from '../auth/index.js';
 import type { SchemaApi } from '../schema/index.js';
 import type { SessionControlOptions } from './context/index.js';
 import type { CallableReference, InputOfReference, OutputOfReference } from './reference.js';
 import type { SessionRequestOptions } from './routing/index.js';
 import type { ClientSession } from './session.js';
 import type { ViewCatalog } from './views/index.js';
-import { type AuthApi } from '../auth/index.js';
 import { type Binary, type Call, type Input, type Result, type Stream } from '../client/index.js';
 import { type GraphApi } from '../graph/index.js';
 /** Exact live Session surface captured by one credential-bound Kernel view. */
 export interface BoundSessionSource {
     readonly kernel: IssuerId;
     readonly schema: SchemaApi;
+    readonly auth: Pick<AuthApi, 'admit'>;
     dispatch(call: Call, options?: SessionRequestOptions): Promise<Result>;
     call(call: Call, options?: SessionRequestOptions): Promise<Input>;
     invoke<const Reference extends CallableReference<unknown>>(reference: Reference, input: InputOfReference<Reference>, options?: SessionRequestOptions): Promise<OutputOfReference<Reference>>;

package/dist/session/bound.js

@@ -1,4 +1,4 @@
-import { createAuth } from '../auth/index.js';
+import { createAuth } from '../auth/auth.js';
 import { call as createCall, } from '../client/index.js';
 import { createGraph } from '../graph/index.js';
 /** Capture one Session into the ordinary graph, auth, and invocation Kernel journey. */
@@ -7,6 +7,7 @@ export function bindSession(source, controls) {
         invalid();
     const admittedControls = admitControls(controls);
     const dispatchSource = capture(source, 'dispatch');
+    const admitSource = capture(source.auth, 'admit');
     const callSource = capture(source, 'call');
     const invokeSource = capture(source, 'invoke');
     const streamSource = capture(source, 'stream');
@@ -14,6 +15,7 @@ export function bindSession(source, controls) {
     const viewsForSource = capture(source, 'viewsFor');
     const schemaSource = captureSchema(source.schema);
     const dispatch = (input, options) => dispatchSource(input, requestOptions(options, admittedControls));
+    const admit = (input, options) => admitSource(input, mergeOptions(options, admittedControls));
     const call = (input, options) => callSource(input, requestOptions(options, admittedControls));
     const invoke = (reference, input, options) => invokeSource(reference, input, requestOptions(options, admittedControls));
     const stream = (input, options) => streamSource(input, requestOptions(options, admittedControls));
@@ -26,7 +28,7 @@ export function bindSession(source, controls) {
     const dependencies = (origin, options) => schemaSource.dependencies(origin, controlOptions(options, admittedControls));
     const schema = Object.freeze({ install, uninstall, inspect, bundle, dependencies });
     const graph = createGraph(call);
-    const auth = createAuth((target, input, options) => call(createCall(target, input), options));
+    const auth = createAuth((target, input, options) => call(createCall(target, input), options), admit);
     return Object.freeze({
         ...graph,
         kernel: source.kernel,

package/dist/session/discovery/index.d.ts

@@ -4,6 +4,7 @@ import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
 import type { SessionSnapshot } from './snapshot.js';
 export type { SessionSnapshot } from './snapshot.js';
+export { boundedResponse, requireExactResponse } from './publication.js';
 export interface SessionDiscovery {
     readonly kernel: IssuerId;
     publication(operation: SessionOperation): Promise<publication.Publication>;

package/dist/session/discovery/index.js

@@ -1,6 +1,7 @@
 import { BundleDiscovery } from './bundle.js';
 import { SessionDiscovery as SessionDiscoveryImplementation } from './discovery.js';
 import { PublicationDiscovery } from './publication.js';
+export { boundedResponse, requireExactResponse } from './publication.js';
 export function createSessionDiscovery(options) {
     return new SessionDiscoveryImplementation(options.kernel, options.policy, new PublicationDiscovery({
         kernel: options.kernel,

package/dist/session/reference.d.ts

@@ -37,4 +37,5 @@ export declare function reference<const Callable extends ResolvedFunction | Exec
 /** Project one exact resolved instance Method into a receiver-bound typed Client reference. */
 export declare function reference<const Callable extends ExecutableInstanceMethod>(domain: Pick<Domain, 'origin' | 'revision'>, callable: Callable): InstanceCallableReference<ReferenceInput<Callable>, ReferenceOutput<Callable>>;
 export declare function admitReference(input: CallableReference<unknown>): CallableReference<unknown>;
+export declare function matchesCallable(target: PathValue, callable: KeyType.Callable): boolean;
 export {};

package/dist/session/reference.js

@@ -52,7 +52,7 @@ export function admitReference(input) {
         outputMode: input.outputMode,
     });
 }
-function matchesCallable(target, callable) {
+export function matchesCallable(target, callable) {
     const coordinate = callableAddress(callable);
     const { anchor, steps } = target.ast;
     const last = steps.at(-1);

package/dist/session/session.d.ts

@@ -2,6 +2,7 @@ import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { PathLike } from '@astrale-os/kernel-core/path';
 import type { Domain } from '@astrale-os/kernel-dsl/v1/domain';
 import type { publication } from '@astrale-os/kernel-protocol';
+import type { AuthApi } from '../auth/index.js';
 import type { Call, Input, Result } from '../client/index.js';
 import type { DomainBinding, GraphApi } from '../graph/index.js';
 import type { ClientFactory, ClientPool as ClientPoolType } from '../pool/index.js';
@@ -42,6 +43,7 @@ export declare class ClientSession {
     readonly kernel: IssuerId;
     readonly schema: SchemaApi;
     readonly graph: GraphApi;
+    readonly auth: AuthApi;
     private readonly ownedPool?;
     private readonly discovery;
     private readonly dispatcher;

package/dist/session/session.js

@@ -1,6 +1,7 @@
 import { Path } from '@astrale-os/kernel-core/path';
 import { callableFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
-import { Client } from '../client/index.js';
+import { createAuth } from '../auth/auth.js';
+import { Client, acceptCall } from '../client/index.js';
 import { SessionError } from '../errors/index.js';
 import { createDomainBinding } from '../graph/domain/binding.js';
 import { createGraph } from '../graph/index.js';
@@ -9,7 +10,8 @@ import { createSchema, DEFAULT_SCHEMA_LIFECYCLE_TIMEOUT_MS } from '../schema/ind
 import { AutoTransport } from '../transport/auto/index.js';
 import { HttpTransport } from '../transport/http/index.js';
 import { WebSocketTransport } from '../transport/websocket/index.js';
-import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
+import { admitFunction } from './admission.js';
+import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, allowEndpoint, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
 import { createSessionDiscovery } from './discovery/index.js';
 import { admitReference } from './reference.js';
 import { admitEnvelopeTransport, admitRequestOptions, admitSessionAuth, requireResultKind, RouteCache, SessionDispatcher, } from './routing/index.js';
@@ -20,6 +22,7 @@ export class ClientSession {
     kernel;
     schema;
     graph;
+    auth;
     ownedPool;
     discovery;
     dispatcher;
@@ -80,12 +83,25 @@ export class ClientSession {
             acquisitionOperation: () => this.operation(undefined),
         });
         this.routes = new RouteCache(policy.maximumRouteAgeMs, undefined, options.routeStore);
+        const auth = admitSessionAuth(options.auth);
+        const admission = {
+            kernel: this.kernel,
+            auth,
+            source: () => {
+                allowEndpoint(sourceEndpoint, policy);
+                return pool.clientFor({ transport: 'http', url: sourceEndpoint });
+            },
+            fetch: fetchImpl,
+            policy,
+            limits: { maximumPublicationBytes, maximumBundleBytes },
+            maximumResponseBytes,
+        };
         this.dispatcher = new SessionDispatcher({
             kernel: this.kernel,
             sourceEndpoint,
             pool,
             websocketAvailable,
-            auth: admitSessionAuth(options.auth),
+            auth,
             cache: this.routes,
             policy,
             envelopeTransport: admitEnvelopeTransport(options.envelopeTransport ?? 'http'),
@@ -97,6 +113,10 @@ export class ClientSession {
             lifecycleTimeoutMs: schemaLifecycleTimeoutMs,
         });
         this.graph = createGraph((call, options) => this.call(call, options));
+        this.auth = createAuth((target, input, options) => this.call({ target, input }, options), (call, options) => {
+            const operation = this.operation(admitControlOptions(options));
+            return admitFunction(admission, acceptCall(call), options, operation);
+        });
     }
     /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
     bind(domain) {

package/dist/session/session.typecheck.js

@@ -12,6 +12,13 @@ void request;
 void snapshot;
 const observedPublication = session.publication(control);
 void observedPublication;
+const admitted = session.auth.admit({
+    target: Path.parse('/:example.test:function.write'),
+    input: {},
+}, { attenuation: { kind: 'identity', self: true }, ...control });
+void admitted;
+// @ts-expect-error Admission belongs to Auth, not the top-level Session.
+void session.admit({ target: Path.parse('/:example.test:function.write'), input: {} });
 const credentials = createSessionCredentialProvider({
     ttlSeconds: 60,
     mint: async () => minted,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.70",
+  "version": "0.6.0-beta.71",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",
@@ -65,18 +65,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.53",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.38",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.59",
+    "@astrale-os/kernel-core": "0.9.0-beta.54",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.39",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.60",
     "@tanstack/pacer": "0.20.1",
     "msgpackr": "^2.0.5"
   },
   "devDependencies": {
-    "@astrale-os/kernel-server": "0.5.0-beta.61",
+    "@astrale-os/kernel-server": "0.5.0-beta.62",
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "@types/node": "^22.0.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "build": "tsc",