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

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

@@ -0,0 +1,397 @@
+import { type JWTPayload } from 'jose';
+import { z } from 'zod';
+/**
+ * Thrown when a refresh succeeds but the IdP mints an access token whose `aud`
+ * does not match the one the caller requested. Distinct from a transport/grant
+ * failure: the session is *healthy*, the IdP simply will not issue that
+ * audience (e.g. WorkOS AuthKit ignores the `audience` param and stamps a fixed
+ * API audience per environment). Re-login does not help — callers must target
+ * an instance whose audience equals `actual`, or reconfigure the IdP/bookmark.
+ */
+export declare class IdpAudienceMismatchError extends Error {
+    readonly requested: string;
+    readonly actual: string | undefined;
+    constructor(requested: string, actual: string | undefined);
+}
+/**
+ * A token-endpoint request that the IdP answered with an OAuth error (or that
+ * failed at the HTTP layer). Carries the structured OAuth `error` code so
+ * callers can tell a definitively dead grant (`invalid_grant`) from a
+ * transient outage — the message string alone cannot.
+ */
+export declare class OAuthTokenError extends Error {
+    /** OAuth `error` code, e.g. `invalid_grant`. */
+    readonly code?: string;
+    /** OAuth `error_description`. */
+    readonly description?: string;
+    /** HTTP status of the token response. */
+    readonly status?: number;
+    constructor(args: {
+        code?: string;
+        description?: string;
+        status?: number;
+    });
+}
+export type RefreshFailureKind = 'session-ended' | 'org-rejected' | 'transient' | 'unknown';
+/**
+ * Classify a `refreshSession` failure so callers only demand a re-login when
+ * the grant is actually dead. `org-rejected` = healthy session, wrong/stale
+ * org scope (re-login can't fix it); 5xx/429 and fetch-layer failures are
+ * transient — the cached session is likely still valid.
+ */
+export declare function classifyRefreshFailure(e: unknown): RefreshFailureKind;
+export declare const OidcMetadataSchema: z.ZodObject<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodOptional<z.ZodString>;
+    token_endpoint: z.ZodString;
+    jwks_uri: z.ZodString;
+    device_authorization_endpoint: z.ZodOptional<z.ZodString>;
+    revocation_endpoint: z.ZodOptional<z.ZodString>;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    grant_types_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    response_types_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    code_challenge_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodOptional<z.ZodString>;
+    token_endpoint: z.ZodString;
+    jwks_uri: z.ZodString;
+    device_authorization_endpoint: z.ZodOptional<z.ZodString>;
+    revocation_endpoint: z.ZodOptional<z.ZodString>;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    grant_types_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    response_types_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    code_challenge_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodOptional<z.ZodString>;
+    token_endpoint: z.ZodString;
+    jwks_uri: z.ZodString;
+    device_authorization_endpoint: z.ZodOptional<z.ZodString>;
+    revocation_endpoint: z.ZodOptional<z.ZodString>;
+    scopes_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    grant_types_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    response_types_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    code_challenge_methods_supported: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, z.ZodTypeAny, "passthrough">>;
+export type OidcMetadata = z.infer<typeof OidcMetadataSchema>;
+export declare const IdpClientConfigSchema: z.ZodObject<{
+    client_id: z.ZodOptional<z.ZodString>;
+    client_secret_env: z.ZodOptional<z.ZodString>;
+    redirect_uris: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    scope: z.ZodOptional<z.ZodString>;
+    public: z.ZodOptional<z.ZodBoolean>;
+    token_response: z.ZodOptional<z.ZodEnum<["oauth", "workos-authkit"]>>;
+    token_request_format: z.ZodOptional<z.ZodEnum<["form", "json"]>>;
+    workos_application_id: z.ZodOptional<z.ZodString>;
+    workos_application_type: z.ZodOptional<z.ZodEnum<["oauth", "m2m"]>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    client_id: z.ZodOptional<z.ZodString>;
+    client_secret_env: z.ZodOptional<z.ZodString>;
+    redirect_uris: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    scope: z.ZodOptional<z.ZodString>;
+    public: z.ZodOptional<z.ZodBoolean>;
+    token_response: z.ZodOptional<z.ZodEnum<["oauth", "workos-authkit"]>>;
+    token_request_format: z.ZodOptional<z.ZodEnum<["form", "json"]>>;
+    workos_application_id: z.ZodOptional<z.ZodString>;
+    workos_application_type: z.ZodOptional<z.ZodEnum<["oauth", "m2m"]>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    client_id: z.ZodOptional<z.ZodString>;
+    client_secret_env: z.ZodOptional<z.ZodString>;
+    redirect_uris: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    scope: z.ZodOptional<z.ZodString>;
+    public: z.ZodOptional<z.ZodBoolean>;
+    token_response: z.ZodOptional<z.ZodEnum<["oauth", "workos-authkit"]>>;
+    token_request_format: z.ZodOptional<z.ZodEnum<["form", "json"]>>;
+    workos_application_id: z.ZodOptional<z.ZodString>;
+    workos_application_type: z.ZodOptional<z.ZodEnum<["oauth", "m2m"]>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type IdpClientConfig = z.infer<typeof IdpClientConfigSchema>;
+export declare const IdpIndexEntrySchema: z.ZodObject<{
+    issuer: z.ZodString;
+    builtIn: z.ZodOptional<z.ZodBoolean>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    issuer: string;
+    builtIn?: boolean | undefined;
+    createdAt: string;
+    updatedAt: string;
+}, {
+    issuer: string;
+    builtIn?: boolean | undefined;
+    createdAt: string;
+    updatedAt: string;
+}>;
+export declare const IdpStoreSchema: z.ZodObject<{
+    idps: z.ZodRecord<z.ZodString, z.ZodObject<{
+        issuer: z.ZodString;
+        builtIn: z.ZodOptional<z.ZodBoolean>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        issuer: string;
+        builtIn?: boolean | undefined;
+        createdAt: string;
+        updatedAt: string;
+    }, {
+        issuer: string;
+        builtIn?: boolean | undefined;
+        createdAt: string;
+        updatedAt: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    idps: Record<string, {
+        issuer: string;
+        builtIn?: boolean | undefined;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+}, {
+    idps: Record<string, {
+        issuer: string;
+        builtIn?: boolean | undefined;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+}>;
+export type IdpStore = z.infer<typeof IdpStoreSchema>;
+export type IdpIndexEntry = z.infer<typeof IdpIndexEntrySchema>;
+export declare const IdpSessionSchema: z.ZodObject<{
+    identity: z.ZodString;
+    idp: z.ZodString;
+    issuer: z.ZodString;
+    subject: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    access_token: z.ZodString;
+    id_token: z.ZodOptional<z.ZodString>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    token_type: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    expires_at: z.ZodOptional<z.ZodString>;
+    claims: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /**
+     * Access tokens by audience. WorkOS mints one `aud` per token, so a
+     * session juggling several instances would otherwise burn a (single-use)
+     * refresh-token rotation on every instance flip. The top-level
+     * `access_token`/`expires_at` stay the most recently minted token for
+     * back-compat with older CLI builds.
+     */
+    tokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>>;
+    updatedAt: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    identity: z.ZodString;
+    idp: z.ZodString;
+    issuer: z.ZodString;
+    subject: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    access_token: z.ZodString;
+    id_token: z.ZodOptional<z.ZodString>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    token_type: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    expires_at: z.ZodOptional<z.ZodString>;
+    claims: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /**
+     * Access tokens by audience. WorkOS mints one `aud` per token, so a
+     * session juggling several instances would otherwise burn a (single-use)
+     * refresh-token rotation on every instance flip. The top-level
+     * `access_token`/`expires_at` stay the most recently minted token for
+     * back-compat with older CLI builds.
+     */
+    tokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>>;
+    updatedAt: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    identity: z.ZodString;
+    idp: z.ZodString;
+    issuer: z.ZodString;
+    subject: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    access_token: z.ZodString;
+    id_token: z.ZodOptional<z.ZodString>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    token_type: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    expires_at: z.ZodOptional<z.ZodString>;
+    claims: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /**
+     * Access tokens by audience. WorkOS mints one `aud` per token, so a
+     * session juggling several instances would otherwise burn a (single-use)
+     * refresh-token rotation on every instance flip. The top-level
+     * `access_token`/`expires_at` stay the most recently minted token for
+     * back-compat with older CLI builds.
+     */
+    tokens: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        access_token: z.ZodString;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>>;
+    updatedAt: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type IdpSession = z.infer<typeof IdpSessionSchema>;
+export type TokenResponse = {
+    access_token?: string;
+    accessToken?: string;
+    id_token?: string;
+    idToken?: string;
+    refresh_token?: string;
+    refreshToken?: string;
+    token_type?: string;
+    scope?: string;
+    expires_in?: number;
+    expiresIn?: number;
+    user?: {
+        id?: string;
+        [key: string]: unknown;
+    };
+    organization_id?: string;
+    authentication_method?: string;
+    error?: string;
+    error_description?: string;
+    [key: string]: unknown;
+};
+export type DeviceAuthorizationResponse = {
+    device_code: string;
+    user_code?: string;
+    verification_uri?: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval?: number;
+    message?: string;
+    [key: string]: unknown;
+};
+export type IdpConfig = {
+    name: string;
+    entry: IdpIndexEntry;
+    metadata: OidcMetadata;
+    client: IdpClientConfig;
+};
+export declare const BUILTIN_WORKOS_IDP_NAME = "workos";
+export declare function idpDir(name: string): string;
+export declare function idpMetadataPath(name: string): string;
+export declare function idpClientPath(name: string): string;
+export declare function idpSessionPath(identityName: string): string;
+export declare function readIdpStore(): Promise<IdpStore>;
+export declare function writeIdpStore(store: IdpStore): Promise<void>;
+export declare function readIdpConfig(name: string): Promise<IdpConfig>;
+export declare function readIdpConfigOrBuiltin(name: string, opts?: {
+    clientId?: string;
+    persist?: boolean;
+}): Promise<IdpConfig>;
+export declare function listIdpConfigs(): Promise<IdpConfig[]>;
+export declare function upsertIdpConfig(args: {
+    name: string;
+    metadata: OidcMetadata;
+    client?: IdpClientConfig;
+    builtIn?: boolean;
+}): Promise<IdpConfig>;
+export declare function removeIdpConfig(name: string): Promise<void>;
+export declare function fetchOidcMetadata(issuer: string): Promise<OidcMetadata>;
+export declare function workosAuthKitMetadata(apiHost?: string, clientId?: string): OidcMetadata;
+export declare function builtinIdpConfig(name: string, clientIdOverride?: string, env?: NodeJS.ProcessEnv): IdpConfig | null;
+export declare function workosClientIdFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function postForm(url: string, params: URLSearchParams): Promise<TokenResponse>;
+export declare function postJson(url: string, bodyInput: Record<string, string>): Promise<TokenResponse>;
+export declare function tokenExpiresAt(token: TokenResponse): string | undefined;
+export declare function decodeTokenClaims(token: string | undefined): JWTPayload | undefined;
+export declare function tokenAudienceMatches(token: string | undefined, audience: string): boolean;
+export declare function subjectFromToken(token: TokenResponse, fallback: string): string;
+export declare function issuerFromToken(token: TokenResponse, fallback: string): string;
+export declare function normalizeTokenResponse(token: TokenResponse): TokenResponse;
+export declare function identityNameFromClaims(claims: JWTPayload | undefined, fallback: string): string;
+export declare function saveIdpSession(session: IdpSession): Promise<void>;
+export declare function readIdpSession(identityName: string): Promise<IdpSession | null>;
+export declare function deleteIdpSession(identityName: string): Promise<void>;
+export declare function listIdpSessions(): Promise<IdpSession[]>;
+export declare function isSessionExpired(session: Pick<IdpSession, 'expires_at'> & {
+    access_token?: string;
+}, skewMs?: number): boolean;
+/**
+ * A still-fresh access token usable for `audience`, or undefined when a
+ * refresh is needed. Checks the per-audience `tokens` map first, then the
+ * top-level token's own `aud` claim. Without an `audience`, freshness of the
+ * top-level token is the only requirement.
+ */
+export declare function accessTokenForAudience(session: IdpSession, audience?: string): string | undefined;
+/**
+ * Fold a freshly minted access token into the per-audience map under every
+ * `aud` it carries, dropping entries that have already expired.
+ */
+export declare function withCachedToken(tokens: IdpSession['tokens'], accessToken: string, expiresAt: string | undefined): IdpSession['tokens'];
+export declare function requireClientId(idp: IdpConfig, override?: string): string;
+export declare function resolveClientSecret(idp: IdpConfig, overrideEnv?: string): string | undefined;
+export declare function refreshSession(identityName: string, session: IdpSession, opts?: {
+    readonly audience?: string;
+    readonly organizationId?: string;
+}): Promise<IdpSession>;
+export declare function requestClientCredentials(args: {
+    idp: IdpConfig;
+    clientId?: string;
+    clientSecretEnv?: string;
+    scope?: string;
+    audience?: string;
+}): Promise<TokenResponse>;
+export declare function requestDeviceAuthorization(args: {
+    idp: IdpConfig;
+    clientId?: string;
+    scope?: string;
+    audience?: string;
+}): Promise<DeviceAuthorizationResponse>;
+export declare function pollDeviceToken(args: {
+    idp: IdpConfig;
+    deviceCode: string;
+    clientId?: string;
+    clientSecretEnv?: string;
+    intervalSec?: number;
+    expiresInSec: number;
+}): Promise<TokenResponse>;
+export declare function exchangeAuthorizationCode(args: {
+    idp: IdpConfig;
+    code: string;
+    redirectUri: string;
+    codeVerifier?: string;
+    clientId?: string;
+    clientSecretEnv?: string;
+}): Promise<TokenResponse>;
+export type WorkosApplication = {
+    id: string;
+    client_id?: string;
+    name?: string;
+    application_type?: 'oauth' | 'm2m';
+    scopes?: string[];
+    redirect_uris?: Array<{
+        uri?: string;
+        default?: boolean;
+    }>;
+    uses_pkce?: boolean;
+};
+export declare function fetchWorkosApplication(args: {
+    apiKeyEnv: string;
+    app: string;
+}): Promise<WorkosApplication>;

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

@@ -0,0 +1,36 @@
+import type { InstanceInfo } from '../admin/instance/model';
+import type { AstraleConfig } from './config';
+import { type AdminTargetCommandOpts, type ResolvedAdminTarget } from './admin-target';
+import { type InstanceStore } from './instance';
+export type InstanceTargetRequest = {
+    source: 'active';
+} | {
+    source: 'name';
+    name: string;
+} | {
+    source: 'admin';
+} | {
+    source: 'url';
+    url: string;
+    name?: string;
+    kernelIssuer?: string;
+};
+export type ResolvedInstanceTarget = {
+    name?: string;
+    source: 'bookmark' | 'managed' | 'admin' | 'url';
+    url: string;
+    kernelIssuer: string;
+    domainIssuer?: string;
+    defaultIdentity?: string;
+    caFile?: string;
+};
+export type ResolveInstanceTargetOpts = {
+    config: AstraleConfig;
+    instances?: InstanceStore;
+    admin?: AdminTargetCommandOpts;
+    managed?: (slug: string) => Promise<InstanceInfo>;
+};
+export declare function resolveInstanceTarget(request: InstanceTargetRequest, opts: ResolveInstanceTargetOpts): Promise<ResolvedInstanceTarget>;
+export declare function couldBeConfiguredAdminInstance(identifier: string, config: AstraleConfig): boolean;
+export declare function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInstanceTarget;
+export declare function isManagedInstanceNotFound(error: unknown): boolean;

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

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import type { AstraleConfig } from './config';
+import { type RegistryMode } from './validation';
+export declare const InstanceKindSchema: z.ZodEnum<["bookmark"]>;
+export type InstanceKind = z.infer<typeof InstanceKindSchema>;
+export declare const InstanceEntrySchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    issuer: z.ZodOptional<z.ZodString>;
+    domainIssuer: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<["bookmark"]>>;
+    mode: z.ZodOptional<z.ZodEnum<["local", "remote"]>>;
+    defaultIdentity: z.ZodOptional<z.ZodString>;
+    caFile: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url?: string | undefined;
+    issuer?: string | undefined;
+    domainIssuer?: string | undefined;
+    createdAt?: string | undefined;
+    slug?: string | undefined;
+    name?: string | undefined;
+    kind?: "bookmark" | undefined;
+    mode?: "local" | "remote" | undefined;
+    defaultIdentity?: string | undefined;
+    caFile?: string | undefined;
+    organizationId?: string | undefined;
+}, {
+    url?: string | undefined;
+    issuer?: string | undefined;
+    domainIssuer?: string | undefined;
+    createdAt?: string | undefined;
+    slug?: string | undefined;
+    name?: string | undefined;
+    kind?: "bookmark" | undefined;
+    mode?: "local" | "remote" | undefined;
+    defaultIdentity?: string | undefined;
+    caFile?: string | undefined;
+    organizationId?: string | undefined;
+}>;
+export declare const InstanceStoreSchema: z.ZodObject<{
+    active: z.ZodString;
+    instances: z.ZodRecord<z.ZodString, z.ZodObject<{
+        url: z.ZodOptional<z.ZodString>;
+        issuer: z.ZodOptional<z.ZodString>;
+        domainIssuer: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<["bookmark"]>>;
+        mode: z.ZodOptional<z.ZodEnum<["local", "remote"]>>;
+        defaultIdentity: z.ZodOptional<z.ZodString>;
+        caFile: z.ZodOptional<z.ZodString>;
+        organizationId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url?: string | undefined;
+        issuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        createdAt?: string | undefined;
+        slug?: string | undefined;
+        name?: string | undefined;
+        kind?: "bookmark" | undefined;
+        mode?: "local" | "remote" | undefined;
+        defaultIdentity?: string | undefined;
+        caFile?: string | undefined;
+        organizationId?: string | undefined;
+    }, {
+        url?: string | undefined;
+        issuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        createdAt?: string | undefined;
+        slug?: string | undefined;
+        name?: string | undefined;
+        kind?: "bookmark" | undefined;
+        mode?: "local" | "remote" | undefined;
+        defaultIdentity?: string | undefined;
+        caFile?: string | undefined;
+        organizationId?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    active: string;
+    instances: Record<string, {
+        url?: string | undefined;
+        issuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        createdAt?: string | undefined;
+        slug?: string | undefined;
+        name?: string | undefined;
+        kind?: "bookmark" | undefined;
+        mode?: "local" | "remote" | undefined;
+        defaultIdentity?: string | undefined;
+        caFile?: string | undefined;
+        organizationId?: string | undefined;
+    }>;
+}, {
+    active: string;
+    instances: Record<string, {
+        url?: string | undefined;
+        issuer?: string | undefined;
+        domainIssuer?: string | undefined;
+        createdAt?: string | undefined;
+        slug?: string | undefined;
+        name?: string | undefined;
+        kind?: "bookmark" | undefined;
+        mode?: "local" | "remote" | undefined;
+        defaultIdentity?: string | undefined;
+        caFile?: string | undefined;
+        organizationId?: string | undefined;
+    }>;
+}>;
+export type InstanceEntry = z.infer<typeof InstanceEntrySchema>;
+export type InstanceStore = z.infer<typeof InstanceStoreSchema>;
+export type AddInstanceOpts = {
+    url?: string;
+    slug?: string;
+    name?: string;
+    kind?: InstanceKind;
+    mode?: RegistryMode;
+    issuer?: string;
+    domainIssuer?: string;
+    defaultIdentity?: string;
+    caFile?: string;
+    organizationId?: string;
+};
+export type ResolvedInstance = {
+    name: string;
+    kind: InstanceKind | 'managed';
+    url: string;
+    issuer?: string;
+    domainIssuer?: string;
+    createdAt?: string;
+    defaultIdentity?: string;
+    caFile?: string;
+    mode?: RegistryMode;
+    status?: string;
+};
+export declare function sanitizeStore(store: InstanceStore): {
+    store: InstanceStore;
+    changed: boolean;
+};
+/**
+ * Invalidate the one-process bookmark snapshot. Long-lived compatibility
+ * consumers call this before a read so CLI writes made by another process are
+ * observable; one-shot commands normally never need it.
+ */
+export declare function resetInstancesMemo(): void;
+export declare function readInstances(_config?: AstraleConfig, opts?: {
+    persist?: boolean;
+}): Promise<InstanceStore>;
+export declare function writeInstances(store: InstanceStore): Promise<void>;
+export declare function assertNoCollision(store: InstanceStore, identifiers: string[], ignoreKey?: string): void;
+export declare function resolveInstanceKey(store: InstanceStore, identifier: string): string | null;
+export declare function addInstance(key: string, opts?: AddInstanceOpts): Promise<InstanceEntry>;
+export declare function upsertInstance(key: string, opts?: AddInstanceOpts): Promise<{
+    entry: InstanceEntry;
+    created: boolean;
+}>;
+/**
+ * Bookmark an admin-managed instance under `key` (url = issuer = the
+ * normalized kernel URL). Reports the previous URL when an existing
+ * bookmark was repointed to a different kernel so callers can warn.
+ */
+export declare function upsertManagedBookmark(key: string, slug: string, rawUrl: string, organizationId?: string): Promise<{
+    entry: InstanceEntry;
+    repointedFrom?: string;
+}>;
+export declare function removeInstance(key: string): Promise<void>;
+export declare function setActive(identifier: string): Promise<string>;
+export declare function clearActive(identifier: string): Promise<void>;
+export declare function getActive(config?: AstraleConfig): Promise<InstanceEntry & {
+    name: string;
+}>;
+export declare function resolveInstance(identifier: string, config?: AstraleConfig): Promise<ResolvedInstance>;
+export declare function resolveKernelUrl(opts: {
+    url?: string;
+    instance?: string;
+}, config: AstraleConfig): Promise<string>;
+/**
+ * The bookmarked org id for the instance matching `audience`'s origin —
+ * consulted before the router's eventually-consistent `/auth/org`.
+ */
+export declare function orgIdForAudience(audience: string): Promise<string | undefined>;
+export declare function normalizeInstanceKernelUrl(url: string): string;
+export declare function normalizeIssuerUrl(url: string): string;

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

@@ -0,0 +1,30 @@
+import { type Ora } from 'ora';
+import { type RawOutputOpts } from './output';
+export declare const log: {
+    info: (msg: string) => void;
+    success: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    step: (msg: string) => void;
+    dim: (msg: string) => void;
+};
+/** Report an error with hint (when present) and exit. Commands that carry
+ *  RawOutputOpts should pass them so machine consumers (--json/--raw/piped)
+ *  get one structured JSON line on stderr instead of the pretty ✖ view. */
+export declare function fatal(e: unknown, opts?: RawOutputOpts): never;
+/** Shortcut for stub commands that aren't wired in v1 (§15). */
+export declare function fatalNotImplemented(feature: string, hint?: string): never;
+/**
+ * Run an async operation behind a spinner. Pass `enabled: false` for
+ * machine-readable output modes. Errors are rethrown after the spinner is
+ * stopped (✖ label failed).
+ *
+ * On success the spinner line is cleared — commands print their own result.
+ * Pass `opts.success` to instead persist a single final line
+ * (✔ <success text> <elapsed>) so a command ends on one line, not a
+ * spinner line + result line pair.
+ */
+export declare function withSpinner<T>(label: string, enabled: boolean, fn: () => Promise<T>, opts?: {
+    success?: (result: T) => string;
+}): Promise<T>;
+export declare function spinner(text: string): Ora;