@astrale-os/sdk 0.5.0-beta.84 → 0.5.0-beta.86

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.0-beta.86](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.85...sdk-v0.5.0-beta.86) (2026-08-30)
+
+
+### Features
+
+* support trusted Domain token-exchange authority ([#352](https://github.com/astrale-os/sdk/issues/352)) ([8bec391](https://github.com/astrale-os/sdk/commit/8bec3915afad8aef6fab66d6e8906ea89ca8ad39))
+
+## [0.5.0-beta.85](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.84...sdk-v0.5.0-beta.85) (2026-08-30)
+
+
+### Features
+
+* **dev:** accept file-backed operator credentials ([#350](https://github.com/astrale-os/sdk/issues/350)) ([8575644](https://github.com/astrale-os/sdk/commit/8575644124ae21014aafcbafd98a8465da980e83))
+
 ## [0.5.0-beta.84](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.83...sdk-v0.5.0-beta.84) (2026-08-30)
 
 

package/dist/deployment/adapter/development/context.d.ts

@@ -3,6 +3,8 @@ import type { DevelopmentPlacement } from './placement.js';
 export interface DevelopmentOverrides {
     readonly publicUrl?: string;
     readonly localPort?: number;
+    /** Private operator credential used by installation-owning adapters only. */
+    readonly credentialFile?: string;
 }
 /** Provider-neutral inputs retained for one complete development session. */
 export interface DevelopmentContext extends DevelopmentInput {

package/dist/execution/identity/exchange.d.ts

@@ -4,6 +4,15 @@ import type { IdentityNetworkPolicy, VerificationBasisResolver } from './jwks.js
 import type { SigningMaterial } from './signing.js';
 export interface ExchangeOptions {
     readonly maximumTtlSeconds?: number;
+    /** Authority carried by the exchanged Domain credential. Defaults to the authenticated caller. */
+    readonly grantMode?: ExchangeGrantMode;
+}
+export type ExchangeGrantMode = 'caller' | 'union';
+interface AcceptedExchangeOptions {
+    readonly maximumTtlSeconds: number;
+    readonly grantMode: ExchangeGrantMode;
 }
 export declare function maximumExchangeTtl(input: ExchangeOptions | undefined): number;
-export declare function tokenExchange(issuer: IssuerId, subject: string, signing: SigningMaterial, policy: IdentityNetworkPolicy, verification: VerificationBasisResolver, maximumTtlSeconds: number): exchange.Provider;
+export declare function tokenExchange(issuer: IssuerId, subject: string, signing: SigningMaterial, policy: IdentityNetworkPolicy, verification: VerificationBasisResolver, maximumTtlSeconds: number, grantMode?: ExchangeGrantMode): exchange.Provider;
+export declare function exchangeOptions(input: ExchangeOptions | undefined): AcceptedExchangeOptions;
+export {};

package/dist/execution/identity/exchange.js

@@ -8,21 +8,27 @@ import { CredentialRejected, IssuerUnavailable } from './errors.js';
 import { verifyCredential, verifyCredentialAgainst } from './jwks.js';
 const DEFAULT_MAXIMUM_TTL_SECONDS = 300;
 export function maximumExchangeTtl(input) {
-    if (input === undefined)
-        return DEFAULT_MAXIMUM_TTL_SECONDS;
+    return acceptExchangeOptions(input).maximumTtlSeconds;
+}
+function acceptExchangeOptions(input) {
+    if (input === undefined) {
+        return Object.freeze({ maximumTtlSeconds: DEFAULT_MAXIMUM_TTL_SECONDS, grantMode: 'caller' });
+    }
     if (input === null ||
         typeof input !== 'object' ||
         Array.isArray(input) ||
-        Reflect.ownKeys(input).some((key) => key !== 'maximumTtlSeconds')) {
+        Reflect.ownKeys(input).some((key) => key !== 'maximumTtlSeconds' && key !== 'grantMode')) {
         throw new TypeError('Execution identity tokenExchange options are invalid.');
     }
     const value = input.maximumTtlSeconds ?? DEFAULT_MAXIMUM_TTL_SECONDS;
     if (!Number.isSafeInteger(value) || value < 1) {
         throw new TypeError('tokenExchange.maximumTtlSeconds must be a positive safe integer.');
     }
-    return value;
+    const grantMode = input.grantMode ?? 'caller';
+    return Object.freeze({ maximumTtlSeconds: value, grantMode: acceptExchangeGrantMode(grantMode) });
 }
-export function tokenExchange(issuer, subject, signing, policy, verification, maximumTtlSeconds) {
+export function tokenExchange(issuer, subject, signing, policy, verification, maximumTtlSeconds, grantMode = 'caller') {
+    const acceptedGrantMode = acceptExchangeGrantMode(grantMode);
     return Object.freeze({
         async exchange(request, context) {
             try {
@@ -45,7 +51,7 @@ export function tokenExchange(issuer, subject, signing, policy, verification, ma
                 const token = await new SignJWT({
                     grant: {
                         v: 1,
-                        expr: { kind: 'identity', credential: carried.credential },
+                        expr: exchangeGrant(acceptedGrantMode, carried.credential),
                     },
                 })
                     .setProtectedHeader({
@@ -81,6 +87,27 @@ export function tokenExchange(issuer, subject, signing, policy, verification, ma
         },
     });
 }
+export function exchangeOptions(input) {
+    return acceptExchangeOptions(input);
+}
+function exchangeGrant(mode, credential) {
+    const caller = Object.freeze({ kind: 'identity', credential });
+    if (mode === 'caller')
+        return caller;
+    return Object.freeze({
+        kind: 'union',
+        operands: Object.freeze([
+            Object.freeze({ kind: 'identity', self: true }),
+            caller,
+        ]),
+    });
+}
+function acceptExchangeGrantMode(input) {
+    if (input !== 'caller' && input !== 'union') {
+        throw new TypeError('tokenExchange.grantMode must be caller or union.');
+    }
+    return input;
+}
 function requireProfile(input, profile) {
     const expected = ['aud', 'delegation', 'exp', 'iat', 'iss', 'sub'];
     const actual = Object.keys(input.claims).sort();

package/dist/execution/identity/identity.js

@@ -1,7 +1,7 @@
 import { admit, authenticate } from './authentication.js';
 import { publicationDelivery } from './delivery.js';
 import { httpIssuer } from './errors.js';
-import { maximumExchangeTtl, tokenExchange } from './exchange.js';
+import { exchangeOptions, tokenExchange } from './exchange.js';
 import { createVerificationBasisResolver } from './jwks.js';
 import { signing } from './signing.js';
 /** Create one stateless execution identity backed by an asymmetric private JWK. */
@@ -37,7 +37,10 @@ export function createIdentity(input) {
     });
     const exchangeProvider = input.tokenExchange === false
         ? undefined
-        : tokenExchange(issuer, input.subject, material, policy, verification, maximumExchangeTtl(input.tokenExchange));
+        : (() => {
+            const options = exchangeOptions(input.tokenExchange);
+            return tokenExchange(issuer, input.subject, material, policy, verification, options.maximumTtlSeconds, options.grantMode);
+        })();
     return identity({
         issuer,
         subject: input.subject,

package/dist/execution/identity/index.d.ts

@@ -1,2 +1,2 @@
 export { createIdentity, identity, type Identity, type IdentityInput } from './identity.js';
-export { maximumExchangeTtl, tokenExchange, type ExchangeOptions } from './exchange.js';
+export { maximumExchangeTtl, tokenExchange, type ExchangeGrantMode, type ExchangeOptions, } from './exchange.js';

package/dist/execution/identity/index.js

@@ -1,2 +1,2 @@
 export { createIdentity, identity } from './identity.js';
-export { maximumExchangeTtl, tokenExchange } from './exchange.js';
+export { maximumExchangeTtl, tokenExchange, } from './exchange.js';

package/dist/execution/index.d.ts

@@ -1,5 +1,5 @@
 export { serve } from './serve.js';
 export type { ExecutionContext, ServedApplication, ServeInput } from './serve.js';
-export { createIdentity, type Identity, type IdentityInput } from './identity/index.js';
+export { createIdentity, type ExchangeGrantMode, type ExchangeOptions, type Identity, type IdentityInput, } from './identity/index.js';
 export { InvocationError } from './invocation/index.js';
 export type { InvocationErrorCode } from './invocation/index.js';

package/dist/execution/index.js

@@ -1,3 +1,3 @@
 export { serve } from './serve.js';
-export { createIdentity } from './identity/index.js';
+export { createIdentity, } from './identity/index.js';
 export { InvocationError } from './invocation/index.js';

package/dist/tooling/cli/arguments.d.ts

@@ -9,6 +9,7 @@ export interface ParsedArgs {
     readonly port?: number;
     readonly host?: string;
     readonly sessionFile?: string;
+    readonly credentialFile?: string;
 }
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/tooling/cli/arguments.js

@@ -8,6 +8,7 @@ export function parseArgs(argv) {
     let port;
     let host;
     let sessionFile;
+    let credentialFile;
     let format;
     let environment;
     const cleaned = [];
@@ -38,6 +39,12 @@ export function parseArgs(argv) {
         else if (argument.startsWith('--session-file=')) {
             sessionFile = sessionFilePath(argument.slice('--session-file='.length));
         }
+        else if (argument === '--credential-file') {
+            credentialFile = absoluteFilePath('--credential-file', rest[++index]);
+        }
+        else if (argument.startsWith('--credential-file=')) {
+            credentialFile = absoluteFilePath('--credential-file', argument.slice('--credential-file='.length));
+        }
         else if (argument === '--format') {
             format = lintFormat(rest[++index]);
         }
@@ -65,9 +72,12 @@ export function parseArgs(argv) {
     if (format !== undefined && command !== 'lint') {
         throw new Error('`--format` is only valid for `lint`.');
     }
-    if ((port !== undefined || host !== undefined || sessionFile !== undefined) &&
+    if ((port !== undefined ||
+        host !== undefined ||
+        sessionFile !== undefined ||
+        credentialFile !== undefined) &&
         command !== 'dev') {
-        throw new Error('`--port`, `--host`, and `--session-file` are only valid for `dev`.');
+        throw new Error('`--port`, `--host`, `--session-file`, and `--credential-file` are only valid for `dev`.');
     }
     if (environment !== undefined && !['dev', 'deploy'].includes(command ?? '')) {
         throw new Error('`--environment` is only valid for dev or deploy.');
@@ -86,6 +96,7 @@ export function parseArgs(argv) {
                 ...(port !== undefined ? { port } : {}),
                 ...(host !== undefined ? { host } : {}),
                 ...(sessionFile !== undefined ? { sessionFile } : {}),
+                ...(credentialFile !== undefined ? { credentialFile } : {}),
             };
         case 'deploy': {
             if (positionals.length > 1)
@@ -176,9 +187,12 @@ function requiredValue(flag, input) {
     return input;
 }
 function sessionFilePath(input) {
-    const value = requiredValue('--session-file', input);
+    return absoluteFilePath('--session-file', input);
+}
+function absoluteFilePath(flag, input) {
+    const value = requiredValue(flag, input);
     if (!isAbsolute(value) || normalize(value) !== value) {
-        throw new Error(`--session-file needs a normalized absolute path, got "${value}"`);
+        throw new Error(`${flag} needs a normalized absolute path, got "${value}"`);
     }
     return value;
 }

package/dist/tooling/cli/help.js

@@ -45,6 +45,9 @@ Options:
                           from --port or adapter configuration.
   --session-file <path>   Write one retained DevelopmentSessionFileV1 snapshot at an
                           absolute path in a caller-owned private directory.
+  --credential-file <path>
+                          Use one private operator credential for adapter-owned Kernel
+                          calls without exposing it in project configuration.
   -h, --help              Show help for dev.
 
 Behavior:
@@ -56,6 +59,8 @@ Behavior:
   The session file is machine-readable and authoritative when requested; human
   stdout/stderr remains diagnostic. It requires an adapter that reports exact
   installed Release evidence.
+  A credential file is read only by the installation-owning adapter. Its value is
+  never forwarded to the Domain runtime or written to the session file.
 
 Adapters:
   cloudflare              Runs the local Worker and optional Vite frontend only;

package/dist/tooling/cli/orchestrate.d.ts

@@ -1 +1,7 @@
+import { type ParsedArgs } from './arguments.js';
+import { develop } from './development/develop.js';
 export declare function run(argv: readonly string[]): Promise<number>;
+export declare function executeDevelopmentCommand(parsed: ParsedArgs, input: {
+    readonly configPath: string;
+    readonly projectDir: string;
+}, execute?: typeof develop): Promise<number>;

package/dist/tooling/cli/orchestrate.js

@@ -41,16 +41,7 @@ export async function run(argv) {
         return 1;
     }
     if (parsed.command === 'dev') {
-        return develop({
-            configPath,
-            projectDir,
-            environment: parsed.env,
-            overrides: Object.freeze({
-                ...(parsed.host === undefined ? {} : { publicUrl: parsed.host }),
-                ...(parsed.port === undefined ? {} : { localPort: parsed.port }),
-            }),
-            ...(parsed.sessionFile === undefined ? {} : { sessionFile: parsed.sessionFile }),
-        });
+        return executeDevelopmentCommand(parsed, { configPath, projectDir });
     }
     const deployment = await loadDeployment(configPath);
     const adapter = deployment.adapter;
@@ -93,6 +84,21 @@ export async function run(argv) {
     info(`Ready: ${result.release.addressing.issuer}`);
     return 0;
 }
+export function executeDevelopmentCommand(parsed, input, execute = develop) {
+    if (parsed.command !== 'dev')
+        throw new TypeError('Development execution requires the dev command.');
+    return execute({
+        configPath: input.configPath,
+        projectDir: input.projectDir,
+        environment: parsed.env,
+        overrides: Object.freeze({
+            ...(parsed.host === undefined ? {} : { publicUrl: parsed.host }),
+            ...(parsed.port === undefined ? {} : { localPort: parsed.port }),
+            ...(parsed.credentialFile === undefined ? {} : { credentialFile: parsed.credentialFile }),
+        }),
+        ...(parsed.sessionFile === undefined ? {} : { sessionFile: parsed.sessionFile }),
+    });
+}
 async function lint(parsed) {
     const { formatLintResult, lintDomain, LinterToolError } = await import('../linter/index.js');
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.84",
+  "version": "0.5.0-beta.86",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",