@ory/argus 0.14.0 → 1.0.0

package/dist/runtime-credential.d.ts

@@ -0,0 +1,140 @@
+/** The broker header a runtime credential must occupy for a request. */
+export type RuntimeAuthorizationHeader = "authorization" | "x-ory-agent-authorization";
+export interface RuntimeAuthenticatedRequest {
+    url: string;
+    init: RequestInit;
+    authorizationHeader: RuntimeAuthorizationHeader;
+    /** Default transport. An mTLS authenticator may ignore this and use its own transport. */
+    fetch: typeof fetch;
+    /** Whether `fetch` is the core's default transport rather than an injected implementation. */
+    usesDefaultFetch?: boolean;
+}
+/**
+ * Executes one noninteractive Agent Security request. Custom Agent SDK
+ * integrations can use this hook to attach a SPIFFE workload identity and run
+ * the request over mTLS without exposing key material to Argus.
+ */
+export type RuntimeRequestAuthenticator = (request: RuntimeAuthenticatedRequest) => Promise<Response>;
+export type RuntimeCredentialKind = "talos" | "injected";
+export interface RuntimeCredential {
+    kind: RuntimeCredentialKind;
+    subject?: string;
+    authenticate: RuntimeRequestAuthenticator;
+}
+export interface ResolveRuntimeCredentialOptions {
+    env?: NodeJS.ProcessEnv;
+    requestAuthenticator?: RuntimeRequestAuthenticator;
+    subject?: string;
+    fetch?: typeof fetch;
+}
+export interface EnrollTalosRuntimeCredentialOptions {
+    projectUrl: string;
+    agentSecurityUrl: string;
+    userToken: string;
+    name: string;
+    idempotencyKey: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    credentialStore?: TalosCredentialStore;
+    identity?: TalosCredentialIdentity;
+    /** @internal Injectable seam for testing default-fetch TLS setup. */
+    configureSystemCaTrust?: () => void;
+}
+export interface EnrolledRuntimeCredential {
+    credential: RuntimeCredential;
+    actorId: string;
+    warnings: string[];
+}
+export type TalosCredentialIdentity = {
+    projectUrl: string;
+    harness: string;
+    sessionId: string;
+    kind: "agent";
+} | {
+    projectUrl: string;
+    harness: string;
+    sessionId: string;
+    kind: "subagent";
+    subAgentType: string;
+    perSpawnId: string;
+};
+export interface StoredTalosCredentialV2 {
+    version: 2;
+    credential: string;
+    actorId: string;
+    credentialId?: string;
+    expiresAt?: string;
+    identity: TalosCredentialIdentity;
+}
+export interface StoredTalosCredentialV1 {
+    version: 1;
+    credential: string;
+    actorId: string;
+}
+export type StoredTalosCredential = StoredTalosCredentialV1 | StoredTalosCredentialV2;
+export type TalosCredentialStoreIdentity = TalosCredentialIdentity | string;
+export interface TalosCredentialStore {
+    load(identity: TalosCredentialStoreIdentity): Promise<StoredTalosCredential | undefined>;
+    save(identity: TalosCredentialStoreIdentity, secret: StoredTalosCredential): Promise<void>;
+}
+export interface CredentialStoreCommandOptions {
+    input?: string;
+}
+export type CredentialStoreCommandRunner = (command: string, args: string[], options?: CredentialStoreCommandOptions) => Promise<{
+    stdout: string;
+}>;
+export interface OsTalosCredentialStoreOptions {
+    platform?: NodeJS.Platform;
+    runCommand?: CredentialStoreCommandRunner;
+}
+export interface NodeTlsCaProvider {
+    getCACertificates?: (type?: "default" | "system" | "bundled" | "extra") => string[];
+    setDefaultCACertificates?: (certificates: ReadonlyArray<string | NodeJS.ArrayBufferView>) => void;
+}
+/**
+ * Make subsequent default Node TLS connections trust both Node's existing CA
+ * set and the operating system trust store. This is process-local and does not
+ * disable certificate verification.
+ */
+export declare function configureSystemCaTrustForDefaultFetch(provider?: NodeTlsCaProvider): boolean;
+export declare class CredentialStoreCommandError extends Error {
+    readonly exitCode?: number | undefined;
+    readonly causeCode?: string | undefined;
+    constructor(message: string, exitCode?: number | undefined, causeCode?: string | undefined);
+}
+export declare const runCredentialStoreCommand: CredentialStoreCommandRunner;
+/** Normalize equivalent project URLs before deriving their credential-store key. */
+export declare function canonicalProjectUrl(projectUrl: string): string;
+export declare function canonicalCredentialIdentity(identity: TalosCredentialStoreIdentity): TalosCredentialIdentity;
+export declare function credentialAccount(identity: TalosCredentialStoreIdentity): string;
+/** OS-backed Talos store. Secrets are never placed in process arguments. */
+export declare function createOsTalosCredentialStore(options?: OsTalosCredentialStoreOptions): TalosCredentialStore;
+export declare function talosRuntimeCredential(apiKey: string, options?: {
+    subject?: string;
+    fetch?: typeof fetch;
+    /** @internal Injectable seam for testing default-fetch TLS setup. */
+    configureSystemCaTrust?: () => void;
+}): RuntimeCredential;
+/** Resolve only noninteractive runtime credentials. No persisted state is read. */
+export declare function resolveRuntimeCredential(options?: ResolveRuntimeCredentialOptions): RuntimeCredential | undefined;
+/** Explicitly enroll a Talos credential and optionally persist it in an OS store. */
+export declare function enrollTalosRuntimeCredential(options: EnrollTalosRuntimeCredentialOptions): Promise<EnrolledRuntimeCredential>;
+export interface EnrollTalosChildRuntimeCredentialOptions {
+    projectUrl: string;
+    agentSecurityUrl: string;
+    name: string;
+    subAgentType: string;
+    idempotencyKey: string;
+    parentCredential: RuntimeCredential;
+    identity: Extract<TalosCredentialIdentity, {
+        kind: "subagent";
+    }>;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    credentialStore?: TalosCredentialStore;
+}
+/** Enroll a separately keyed child using the authenticated parent runtime. */
+export declare function enrollTalosChildRuntimeCredential(options: EnrollTalosChildRuntimeCredentialOptions): Promise<EnrolledRuntimeCredential>;
+export declare function authenticatedRuntimeRequest(credential: RuntimeCredential, request: Omit<RuntimeAuthenticatedRequest, "fetch" | "usesDefaultFetch"> & {
+    fetch?: typeof fetch;
+}): Promise<Response>;