@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

package/dist/types/admin/instance/model.d.ts

@@ -0,0 +1,40 @@
+/** CLI-stable projection of one caller-visible Admin Instance. */
+export type InstanceState = 'provisioning' | 'ready' | 'deleting' | 'failed' | 'deleted';
+export interface InstanceInfo {
+    readonly id: string;
+    readonly slug: string;
+    readonly url: string;
+    readonly hostId?: string;
+    readonly region?: string;
+    readonly state?: InstanceState;
+    readonly phase?: string;
+    readonly error?: string | null;
+    readonly createdAt?: string;
+    readonly organizationId?: string;
+}
+/** An Instance returned through the caller-scoped Admin graph inventory. */
+export interface OwnedInstanceInfo extends InstanceInfo {
+    readonly state: InstanceState;
+}
+export interface DomainInstallReceipt {
+    readonly domain: string;
+    readonly instance: string;
+    readonly origin: string;
+    readonly ok: boolean;
+    readonly installedRevision?: string;
+    readonly error?: string;
+}
+export declare class AdminInstanceNotFoundError extends Error {
+    readonly identifier: string;
+    readonly name = "NotFoundError";
+    constructor(identifier: string);
+}
+export declare class AdminHostNotFoundError extends Error {
+    readonly identifier: string;
+    readonly name = "NotFoundError";
+    constructor(identifier: string);
+}
+/** Match an owner-scoped Instance by slug, canonical Node Path, or bare Node id. */
+export declare function findOwnedInstance(instances: readonly OwnedInstanceInfo[], identifier: string): OwnedInstanceInfo | undefined;
+/** Human-readable location of an Instance (state, region, and Host Path). */
+export declare function formatInstanceLocation(info: InstanceInfo): string;

package/dist/types/connect-core.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Temporary compatibility surface for the observed `@astrale-os/connect-host`
+ * consumer. Keep this file as re-exports only: CLI state and connection owners
+ * remain authoritative, and no Kernel Client implementation type is exposed.
+ */
+export { getDefault, getIdentity, readIdentities } from './identity/registry';
+export type { Identity, IdentityStore } from './identity/registry';
+export { listIdentityKeys, signAs } from './keys/index';
+export { normalizeInstanceKernelUrl, orgIdForAudience, readInstances, resetInstancesMemo, resolveInstance, } from './lib/instance';
+export type { InstanceEntry, InstanceStore, ResolvedInstance } from './lib/instance';
+export { resolveInstanceTarget } from './lib/instance-target';
+export type { ResolvedInstanceTarget } from './lib/instance-target';
+export { readConfig } from './lib/config';
+export type { AstraleConfig } from './lib/config';
+export { IdpOrgMembershipError, IdpRefreshTransientError, resolveCredential, } from './connection/auth';
+export { loginViaIdp, resolveIdpName } from './lib/login-flow';
+export type { DeviceVerification, LoginFlowOpts, LoginResult } from './lib/login-flow';
+export { isSessionExpired, readIdpSession } from './lib/idp';
+export type { IdpSession } from './lib/idp';
+export { AuthError } from './errors';
+export { fetchWithCaFile } from './lib/ca-fetch';
+export { createPaths, paths } from './state/index';

package/dist/types/connection/auth.d.ts

@@ -0,0 +1,33 @@
+import type { AstraleConfig } from '../lib/config';
+import { type Identity } from '../identity/registry';
+export type KeyIdentityAuthOptions = {
+    issuer: string;
+    subject?: string;
+    audience: string;
+};
+/**
+ * Resolve a signed JWT credential from CLI options.
+ *
+ * The **audience** is passed in explicitly by the caller because transport URL
+ * and kernel issuer can differ for remote deployments.
+ *
+ * Three cases, in order of priority:
+ *   1. `opts.creds` — pre-signed credential, returned as-is.
+ *   2. `opts.as` — sign as a named local identity.
+ *   3. Default — sign as the active local identity. If the identity has a
+ *      registration for the target instance, use that target-issued `(iss, sub)`.
+ */
+export declare function resolveCredential(opts: {
+    as?: string;
+    creds?: string;
+    defaultIdentity?: string;
+}, config: AstraleConfig, audience?: string, registrationKey?: string): Promise<string>;
+export declare function resolveKeyIdentityAuthOptions(identity: Identity, config: AstraleConfig, audience?: string, registrationKey?: string): KeyIdentityAuthOptions;
+/** A refresh attempt failed for a reason that re-login will NOT fix. */
+export declare class IdpRefreshTransientError extends Error {
+    constructor(message: string);
+}
+/** The IdP refused to scope the session to the target's organization. */
+export declare class IdpOrgMembershipError extends Error {
+    constructor(message: string);
+}

package/dist/types/errors.d.ts

@@ -0,0 +1,23 @@
+export declare class AstraleError extends Error {
+    code: string;
+    hint?: string;
+    constructor(code: string, message: string, hint?: string);
+}
+export declare class AuthError extends AstraleError {
+    constructor(message: string, hint?: string);
+}
+export declare class IssuerUnreachableError extends AstraleError {
+    constructor(url: string, hint?: string);
+}
+export declare class ReservedSlugError extends AstraleError {
+    constructor(slug: string);
+}
+export declare class IdentifierCollisionError extends AstraleError {
+    constructor(identifier: string, existingEntity: string);
+}
+export declare class IdentityKeyMissingError extends AstraleError {
+    constructor(subject: string);
+}
+export declare class NotImplementedError extends AstraleError {
+    constructor(feature: string, hint?: string);
+}

package/dist/types/identity/registry.d.ts

@@ -0,0 +1,25 @@
+import { type Identity, type IdentityMode, type IdentityStore, type Registration } from '../state/index';
+export type { Identity, IdentityStore, Registration } from '../state/index';
+export declare function readIdentities(): Promise<IdentityStore>;
+export declare function createIdentity(name: string, options?: {
+    readonly subject?: string;
+    readonly mode?: IdentityMode;
+    readonly issuer?: string;
+    readonly kid?: string;
+}): Promise<Identity>;
+export declare function deleteIdentity(name: string): Promise<void>;
+export declare function setDefault(name: string): Promise<void>;
+export declare function getDefault(): Promise<Identity & {
+    readonly name: string;
+}>;
+export declare function getIdentity(name: string): Promise<Identity>;
+export declare function upsertIdpIdentity(name: string, options: {
+    readonly subject: string;
+    readonly idp: string;
+    readonly issuer: string;
+    readonly audience?: string;
+    readonly claims?: Readonly<Record<string, unknown>>;
+    readonly use?: boolean;
+}): Promise<Identity>;
+export declare function setRegistration(name: string, instanceSlug: string, registration: Registration): Promise<void>;
+export declare function setIdentityMode(name: string, mode: IdentityMode): Promise<void>;

package/dist/types/keys/algorithm.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve the JOSE algorithm to use with this key. Prefers `privateJwk.alg`
+ * when present, falls back to inferring from `crv`/`kty` so keys generated
+ * by older CLIs that did not stamp `alg`. Throws when neither form resolves.
+ */
+export declare function inferAlg(privateJwk: Record<string, unknown>, keyPath?: string): string;

package/dist/types/keys/credential.d.ts

@@ -0,0 +1,21 @@
+import { type JWK } from 'jose';
+type AuthOptions = {
+    readonly issuer?: string;
+    readonly subject?: string;
+    readonly kid?: string;
+};
+export type AuthBinding = {
+    readonly credential: string;
+    readonly publicKey: {
+        readonly jwk: JWK;
+    };
+};
+export declare function persistAuth(keysDir?: string, opts?: AuthOptions): Promise<AuthBinding>;
+export declare function loadAuth(keysDir?: string, opts?: AuthOptions): Promise<AuthBinding>;
+export declare function resolveAuth(keysDir?: string, opts?: AuthOptions): Promise<AuthBinding>;
+export declare function signAs(subject: string, keysDir?: string, opts?: {
+    readonly issuer?: string;
+    readonly audience?: string;
+    readonly subject?: string;
+}): Promise<string>;
+export {};

package/dist/types/keys/index.d.ts

@@ -0,0 +1,4 @@
+export { acceptKeypair, fileExists, generateEd25519Jwk, importKeypair, keypairPaths, listIdentityKeys, persistKeypair, readKeypair, removeKeypair, } from './pair';
+export { loadAuth, persistAuth, resolveAuth, signAs } from './credential';
+export type { Keypair, KeypairInput, KeypairPaths } from './pair';
+export type { AuthBinding } from './credential';

package/dist/types/keys/pair.d.ts

@@ -0,0 +1,34 @@
+import { type JWK } from 'jose';
+export type KeypairPaths = {
+    readonly privatePath: string;
+    readonly publicPath: string;
+};
+export interface Keypair {
+    readonly privateJwk: JWK;
+    readonly publicJwk: JWK;
+    readonly kid?: string;
+}
+export interface KeypairInput {
+    readonly privateJwk: unknown;
+    readonly publicJwk: unknown;
+}
+/** Preserve manager filenames and confine every subject file to the selected key directory. */
+export declare function keypairPaths(subject: string, keysDir?: string): KeypairPaths;
+export declare function acceptKeypair(input: KeypairInput): Promise<Keypair>;
+export declare function fileExists(path: string): Promise<boolean>;
+export declare function listIdentityKeys(keysDir?: string): Promise<string[]>;
+export declare function generateEd25519Jwk(kid: string): Promise<{
+    readonly privateJwk: JWK;
+    readonly publicJwk: JWK;
+}>;
+export declare function persistKeypair(subject: string, opts?: {
+    readonly keysDir?: string;
+    readonly kid?: string;
+}): Promise<{
+    readonly publicJwk: JWK;
+    readonly privateJwk: JWK;
+    readonly kid: string;
+}>;
+export declare function readKeypair(subject: string, keysDir?: string): Promise<Keypair>;
+export declare function importKeypair(subject: string, input: KeypairInput, keysDir?: string): Promise<Keypair>;
+export declare function removeKeypair(subject: string, keysDir?: string): Promise<void>;

package/dist/types/lib/admin-target.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { AstraleConfig } from './config';
+import type { InstanceStore } from './instance';
+export declare const DEFAULT_ADMIN_TARGET_NAME = "admin";
+export declare const DEFAULT_ADMIN_TARGET_URL = "https://admin.eu.astrale.ai/api";
+export declare const DEFAULT_ADMIN_DOMAIN_ISSUER = "https://admin.beta.astrale.ai";
+export declare const DEFAULT_ADMIN_TARGET_CONFIG: {
+    name: string;
+    url: string;
+    kernelIssuer: string;
+    domainIssuer: string;
+};
+export declare const AdminTargetConfigSchema: z.ZodEffects<z.ZodObject<{
+    /** Friendly name / auth registration slug for direct URL admin targets. */
+    name: z.ZodOptional<z.ZodString>;
+    /** Direct admin kernel URL. */
+    url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    /** Kernel issuer / JWT audience when different from url. */
+    kernelIssuer: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    /** Exact native Admin Domain issuer used by the standard token exchange. */
+    domainIssuer: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    /** Bookmark name for the admin kernel. */
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name?: string | undefined;
+    url?: string | undefined;
+    kernelIssuer?: string | undefined;
+    domainIssuer?: string | undefined;
+    instance?: string | undefined;
+}, {
+    name?: string | undefined;
+    url?: string | undefined;
+    kernelIssuer?: string | undefined;
+    domainIssuer?: string | undefined;
+    instance?: string | undefined;
+}>, {
+    name?: string | undefined;
+    url?: string | undefined;
+    kernelIssuer?: string | undefined;
+    domainIssuer?: string | undefined;
+    instance?: string | undefined;
+}, {
+    name?: string | undefined;
+    url?: string | undefined;
+    kernelIssuer?: string | undefined;
+    domainIssuer?: string | undefined;
+    instance?: string | undefined;
+}>;
+export type AdminTargetConfig = z.infer<typeof AdminTargetConfigSchema>;
+export type AdminTargetCommandOpts = {
+    admin?: string;
+    adminUrl?: string;
+    domainIssuer?: string;
+    instance?: string;
+    url?: string;
+};
+export type AdminTargetSource = 'admin-url' | 'admin' | 'config-instance' | 'config-url' | 'default';
+export type ResolvedAdminTarget = {
+    name: string;
+    url: string;
+    kernelIssuer: string;
+    domainIssuer: string;
+    defaultIdentity?: string;
+    caFile?: string;
+    source: AdminTargetSource;
+    configured: boolean;
+    registrationSlug: string;
+};
+export declare const ADMIN_TARGET_OPTIONS: {
+    flags: string;
+    description: string;
+}[];
+export declare function resolveAdminTarget(opts: AdminTargetCommandOpts, config: AstraleConfig, store?: InstanceStore): Promise<ResolvedAdminTarget>;
+export declare function resolveAdminTargetFromStore(opts: AdminTargetCommandOpts, config: AstraleConfig, store: InstanceStore): ResolvedAdminTarget;

package/dist/types/lib/ca-fetch.d.ts

@@ -0,0 +1,2 @@
+/** Create a Fetch capability whose HTTPS requests trust one CLI-selected CA file. */
+export declare function fetchWithCaFile(caFile: string, fallback?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

package/dist/types/lib/config.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+export declare const AstraleConfigSchema: z.ZodObject<{
+    issuer: z.ZodDefault<z.ZodString>;
+    admin: z.ZodDefault<z.ZodEffects<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        kernelIssuer: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        domainIssuer: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        instance: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string | undefined;
+        url?: string | undefined;
+        kernelIssuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        instance?: string | undefined;
+    }, {
+        name?: string | undefined;
+        url?: string | undefined;
+        kernelIssuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        instance?: string | undefined;
+    }>, {
+        name?: string | undefined;
+        url?: string | undefined;
+        kernelIssuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        instance?: string | undefined;
+    }, {
+        name?: string | undefined;
+        url?: string | undefined;
+        kernelIssuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        instance?: string | undefined;
+    }>>;
+    telemetry: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    issuer: string;
+    admin: {
+        name?: string | undefined;
+        url?: string | undefined;
+        kernelIssuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        instance?: string | undefined;
+    };
+    telemetry: {
+        enabled: boolean;
+    };
+}, {
+    issuer?: string | undefined;
+    admin?: {
+        name?: string | undefined;
+        url?: string | undefined;
+        kernelIssuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        instance?: string | undefined;
+    } | undefined;
+    telemetry?: {
+        enabled?: boolean | undefined;
+    } | undefined;
+}>;
+export type AstraleConfig = z.infer<typeof AstraleConfigSchema>;
+export declare const DEFAULT_CONFIG: AstraleConfig;
+export declare function readConfig(): Promise<AstraleConfig>;
+export declare function writeConfig(config: AstraleConfig): Promise<void>;
+export declare function configExists(): Promise<boolean>;

package/dist/types/lib/format.d.ts

@@ -0,0 +1 @@
+export declare function formatElapsed(ms: number): string;

package/dist/types/lib/idp-session.d.ts

@@ -0,0 +1,33 @@
+import { type IdpSession } from './idp';
+/** No cached session file exists for the identity — only a login creates one. */
+export declare class IdpSessionMissingError extends Error {
+    readonly identityName: string;
+    constructor(identityName: string);
+}
+/** The session needs a refresh but never received a refresh token. */
+export declare class IdpSessionNoRefreshTokenError extends Error {
+    readonly identityName: string;
+    constructor(identityName: string);
+}
+export type EnsureFreshSessionOptions = {
+    audience?: string;
+    organizationId?: string;
+    /**
+     * Org-hint resolver, consulted only when a refresh actually happens.
+     * Defaults to `fetchOrgHint`; injectable for tests.
+     */
+    resolveOrganizationId?: (audience: string) => Promise<string | undefined>;
+};
+export declare function idpSessionLockPath(identityName: string): string;
+/**
+ * Return a session holding a fresh access token for `audience`, refreshing it
+ * if needed. This is the ONLY correct way to refresh: WorkOS refresh tokens
+ * are single-use, so two processes refreshing concurrently burn the same
+ * token — the loser's `invalid_grant` can revoke the whole upstream session.
+ * All refreshes therefore serialize on a per-identity file lock, and waiters
+ * re-read the rotated session instead of re-exchanging.
+ *
+ * `IdpAudienceMismatchError` propagates verbatim (the session is healthy; the
+ * IdP just won't mint that audience).
+ */
+export declare function ensureFreshSession(identityName: string, opts?: EnsureFreshSessionOptions): Promise<IdpSession>;