run402-mcp/sdk/dist/credentials.d.ts

MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.

/**
 * Credential provider interface for the Run402 SDK.
 *
 * The SDK's request kernel calls `getAuth` before each request to obtain
 * signed auth headers, and `getProjectCredentials` to resolve per-project
 * anon/service keys. All filesystem, environment, and session-state access
 * lives inside provider implementations — never in the kernel.
 *
 * Node consumers use {@link NodeCredentialsProvider} from `@run402/sdk/node`
 * which wraps the local keystore + wallet. Sandbox consumers supply their
 * own implementation bound to a session token issued by the supervisor.
 *
 * The two required methods (`getAuth`, `getProjectCredentials`) support every API call.
 * The optional methods let providers opt in to local persistence (keystore
 * writes, active-project tracking). Namespace methods that need a missing
 * optional method throw a descriptive error at runtime.
 */
export interface ProjectKeys {
    anon_key: string;
    service_key: string;
    site_url?: string;
    deployed_at?: string;
    last_deployment_id?: string;
    mailbox_id?: string;
    mailbox_address?: string;
    cached_at?: string;
}
export interface ProjectCredentialCacheInfo {
    source: "local_cache";
    cache_path?: string;
    wallet?: string;
    profile?: string;
}
export interface WalletData {
    address: string;
    privateKey: string;
    created?: string;
    funded?: boolean;
    lastFaucet?: string;
    rail?: "x402" | "mpp" | "lightning";
    /** The Lightning wallet: a budgeted wallet on Run402's Hub; `nwc` is the pairing secret and never leaves the machine. */
    lightning?: {
        wallet_id: string;
        nwc: string;
        lightning_address: string | null;
        budget_sats: number;
        starter_sats: number;
        custody: "run402_hub";
        minted_at: string;
    };
}
/**
 * The active wallet's display identity. `name` is the local profile/selector
 * name (e.g. "kychon", or "default" for the root wallet); `label` is the
 * server-side display name, cached locally and `null` when unknown or offline.
 */
export interface WalletIdentity {
    name: string;
    address: string | null;
    label: string | null;
}
/**
 * Gateway write-approval capabilities. Each is scoped to a target:
 * `org.project.create` → an org, the others → a project.
 */
export type WriteApprovalCapability = "org.project.create" | "project.deploy" | "project.secret.write" | "project.archives.export" | "project.snapshots.manage" | "project.branches.manage";
/** A write-capability target: an org (for `org.project.create`) or a project. */
export interface WriteApprovalTarget {
    org_id?: string;
    project_id?: string;
}
/**
 * Per-request metadata a typed SDK method may pass to {@link
 * CredentialsProvider.getAuth}. `capability` + `target` let a provider decide
 * whether (and which) write approval to attach for a gated write.
 */
export interface AuthRequestMeta {
    /** Diagnostic: the SDK method name (e.g. "projects.provision"). */
    method?: string;
    /** The gateway write capability this request exercises, if any. */
    capability?: WriteApprovalCapability;
    /** The capability's target. */
    target?: WriteApprovalTarget;
}
export interface CredentialsProvider {
    /** Sign exact UTF-8 bytes as an EIP-191 personal message without exposing key material. */
    signPersonalMessage?(message: string): Promise<{
        address: string;
        signature: string;
    }>;
    /**
     * Return per-request auth headers for the given API path, or null if none
     * are available. Typical headers: `SIGN-IN-WITH-X` (SIWE), `Authorization:
     * Bearer ...`. The kernel merges these into the request headers without
     * overwriting headers explicitly set on the request.
     *
     * `metadata` (optional) carries the request's write capability + target so a
     * provider can attach a matching write approval. Providers that
     * ignore it (wallet-only) simply omit the parameter.
     */
    getAuth(path: string, metadata?: AuthRequestMeta): Promise<Record<string, string> | null>;
    /**
     * Resolve the anon/service keys for a project. Returns null when local
     * credentials are absent. This is a credential-cache lookup, not a project
     * existence check.
     */
    getProjectCredentials?(id: string): Promise<ProjectKeys | null>;
    /**
     * @deprecated Use `getProjectCredentials`. This alias is retained only for
     * older custom providers; first-party SDK code must use the explicit name.
     */
    getProject?(id: string): Promise<ProjectKeys | null>;
    /** List locally cached project credentials. Optional and local-cache only; not project inventory. */
    listProjectCredentials?(): Promise<Record<string, ProjectKeys>>;
    /**
     * Persist project keys after a successful provision or deploy. Optional:
     * providers without local storage (pure session providers) may omit this.
     */
    saveProject?(id: string, project: ProjectKeys): Promise<void>;
    /** Partially update a project's stored fields (e.g. mailbox_id, last_deployment_id). Optional. */
    updateProject?(id: string, patch: Partial<ProjectKeys>): Promise<void>;
    /** Remove a project from local storage after deletion. Optional. */
    removeProject?(id: string): Promise<void>;
    /** Set the active/default project id in local state. Optional. */
    setActiveProject?(id: string): Promise<void>;
    /** Get the active/default project id from local state. Optional. */
    getActiveProject?(): Promise<string | null>;
    /**
     * Get the active/current organization id from local state (the CLI's
     * `run402 orgs use`). Optional. Read by the SDK only to disambiguate a
     * gateway `ORGANIZATION_SELECTION_REQUIRED` answer (the MPP Lightning
     * rail's paying organization when the principal belongs to several); it
     * is never sent unprompted and never an authorization input.
     */
    getActiveOrg?(): Promise<string | null>;
    /** Read the local wallet (wallet). Optional — sandbox providers may omit. */
    readWallet?(): Promise<WalletData | null>;
    /** Persist the local wallet. Optional. */
    saveWallet?(data: WalletData): Promise<void>;
    /** Generate a fresh wallet keypair. Optional — Node default uses secp256k1 + keccak for the Ethereum address. */
    createWallet?(): Promise<WalletData>;
    /** Return the absolute path to the local wallet file, for diagnostic output. Optional. */
    getWalletPath?(): string;
    /** Return safe provenance for the local project credential cache. Optional. */
    getProjectCredentialCacheInfo?(): ProjectCredentialCacheInfo;
    /**
     * Return the active wallet's display identity (local name + address + cached
     * server label). The Node provider derives this from the active profile;
     * sandbox/session providers may omit it. Used by {@link Run402.whoami}.
     */
    getWalletIdentity?(): Promise<WalletIdentity | null>;
}
//# sourceMappingURL=credentials.d.ts.map