@geostack/arc 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,632 @@
+import { type JWK } from "jose";
+export type JsonObject = Record<string, unknown>;
+export type ArcRiskLevel = "critical" | "high" | "low" | "medium";
+export type ArcDefaultDecision = "allow" | "ask" | "block";
+export type ArcActionCost = {
+    currency?: string;
+    field: string;
+    mode: "field";
+} | {
+    currency?: string;
+    fixedMinor: number;
+    mode: "fixed";
+};
+export type ArcActionDefinition = {
+    cost?: ArcActionCost;
+    defaultDecision: ArcDefaultDecision;
+    description?: string;
+    enabled?: boolean;
+    input: JsonObject;
+    name: string;
+    output?: JsonObject;
+    risk: ArcRiskLevel;
+    tags?: string[];
+};
+export type ArcActionDefinitions = Record<string, ArcActionDefinition>;
+export type ArcActionSyncItem = {
+    cost_currency?: string | null;
+    cost_field?: string | null;
+    cost_fixed_minor?: number | null;
+    cost_mode?: "field" | "fixed" | "none";
+    default_decision: ArcDefaultDecision;
+    description: string | null;
+    enabled: boolean;
+    input_schema: JsonObject;
+    key: string;
+    name: string;
+    output_schema?: JsonObject | null;
+    risk_level: ArcRiskLevel;
+    tags?: string[];
+};
+export type ArcActionSyncPayload = {
+    actions: ArcActionSyncItem[];
+};
+export type ArcPublicAction = ArcActionSyncItem & {
+    app_id: string;
+    created_at: string;
+    id: string;
+    updated_at: string;
+};
+export type ArcExecutionRequestBody = {
+    action_request_id?: string | null;
+    action_key: string;
+    agent: {
+        display_name: string | null;
+        id: string;
+        type: string;
+    };
+    app_id: string;
+    app_user_id: string;
+    org_id: string;
+    authorization?: {
+        approval_status: string | null;
+        approval_id?: string | null;
+        app_verification_status?: "internal" | "official" | "pending" | "unverified" | "verified";
+        authority_token_use?: "arc_authority";
+        decision: "allow" | "ask";
+        delegation_id: string | null;
+        delegation_status: string | null;
+        issued_by: "arc";
+    };
+    decision: "allow" | "ask";
+    input: unknown;
+    input_hash: string;
+    invocation_id: string;
+    nonce: string;
+    risk_level: ArcRiskLevel;
+    timestamp: string;
+    user: {
+        email: string;
+        id: string;
+        name: string | null;
+    };
+    workspace_id: string;
+};
+export type ArcRequestVerificationResult = {
+    claims: ArcSignedClaims;
+    payload: ArcExecutionRequestBody;
+    valid: true;
+};
+export type ArcSignedClaims = {
+    action_request_id?: string | null;
+    action_key: string;
+    app_id: string;
+    body_hash: string;
+    input_hash: string;
+    invocation_id: string;
+    nonce: string;
+    org_id: string;
+    timestamp: string;
+    workspace_id: string;
+};
+export type ArcAuthorityClaims = ArcSignedClaims & {
+    agent_id: string;
+    app_verification_status: "internal" | "official" | "pending" | "unverified" | "verified";
+    approval_id: string | null;
+    aud: string;
+    decision: "allow" | "ask";
+    delegation_id: string | null;
+    exp: number;
+    human_user_id: string;
+    iat: number;
+    iss: string;
+    jti: string;
+    risk_level: ArcRiskLevel;
+    scope: string;
+    sub: string;
+    token_use: "arc_authority";
+};
+export type ArcNonceReplayStore = {
+    /**
+     * Return true only when this nonce was not seen before and has now been recorded
+     * until expiresAt. Return false for replayed nonces.
+     */
+    useNonce: (nonce: string, expiresAt: Date) => boolean | Promise<boolean>;
+};
+export type ArcInvocationIdempotencyStore = {
+    /**
+     * Return true only when this invocation id was not processed before and has
+     * now been recorded. Return false for duplicate/replayed invocation ids.
+     */
+    useInvocation: (invocationId: string) => boolean | Promise<boolean>;
+};
+export type VerifyArcRequestOptions = {
+    jwks: {
+        keys: JWK[];
+    } | JWK[];
+    maxTimestampSkewMs?: number;
+    nonceStore?: ArcNonceReplayStore;
+    now?: Date;
+    unsafeAllowInMemoryNonceStore?: boolean;
+};
+export type ValidateArcInvocationOptions = {
+    expectedActionKey?: string;
+    expectedAppId?: string;
+    expectedDecision?: "allow" | "ask";
+    expectedOrgId?: string;
+    expectedRiskLevel?: ArcRiskLevel;
+    expectedWorkspaceId?: string;
+    inputSchema?: JsonObject;
+    invocationStore?: ArcInvocationIdempotencyStore;
+};
+export type VerifyArcDelegationOptions = {
+    expectedDelegationId?: string;
+    requireActiveDelegation?: boolean;
+    requireApprovedAsk?: boolean;
+};
+export type VerifyArcExecutionOptions = VerifyArcRequestOptions & ValidateArcInvocationOptions & VerifyArcDelegationOptions;
+export type VerifyArcAuthorityTokenOptions = {
+    expectedActionKey?: string;
+    expectedAppId?: string;
+    expectedAudience?: string;
+    expectedDecision?: "allow" | "ask";
+    expectedDelegationId?: string;
+    expectedIssuer?: string;
+    expectedOrgId?: string;
+    expectedWorkspaceId?: string;
+    jwks: {
+        keys: JWK[];
+    } | JWK[];
+    maxClockSkewMs?: number;
+    nonceStore?: ArcNonceReplayStore;
+    now?: Date;
+};
+export type ArcAuthorityVerificationResult = {
+    claims: ArcAuthorityClaims;
+    expiresAt: Date;
+    valid: true;
+};
+export type ArcAuthorityIntrospectionInput = {
+    apiUrl?: string;
+    appApiKey: string;
+    fetch?: FetchLike;
+    invocationId?: string;
+    signedExecutionId?: string;
+    token?: string;
+};
+export type ArcAuthorityIntrospectionResult = {
+    active: boolean;
+    action: string | null;
+    agent_id: string | null;
+    app_id: string;
+    approval_id: string | null;
+    approval_status: string | null;
+    audience: string | null;
+    decision: ArcDefaultDecision | null;
+    delegation_id: string | null;
+    expires_at: string | null;
+    human_user_id: string | null;
+    invocation_id: string | null;
+    invocation_status: string | null;
+    issuer: string | null;
+    org_id: string | null;
+    reason: string | null;
+    risk_level: ArcRiskLevel | null;
+    scope: string | null;
+    token_use: string | null;
+    workspace_id: string | null;
+};
+export type RequireArcAuthorityOptions = VerifyArcAuthorityTokenOptions;
+export type ArcAuthorityMiddlewareOptions = VerifyArcAuthorityTokenOptions & {
+    actionResolver?: (request: unknown) => string | undefined;
+    tokenResolver?: (request: unknown) => string | undefined;
+};
+export type ArcRequestLike = {
+    body: string | Uint8Array | ArcExecutionRequestBody;
+    headers: Headers | Record<string, string | string[] | undefined>;
+};
+export type ArcActionHandlerContext = {
+    actionKey: string;
+    agent: ArcExecutionRequestBody["agent"];
+    appUserId: string;
+    input: unknown;
+    invocationId: string;
+    payload: ArcExecutionRequestBody;
+    user: ArcExecutionRequestBody["user"];
+};
+export type ArcActionHandler = (context: ArcActionHandlerContext) => Promise<unknown> | unknown;
+export type ArcActionHandlers<TActions extends ArcActionDefinitions> = Partial<Record<keyof TActions & string, ArcActionHandler>>;
+export type HandleActionOptions = Omit<Partial<VerifyArcRequestOptions>, "jwks"> & {
+    apiUrl?: string;
+    jwks?: VerifyArcRequestOptions["jwks"];
+    jwksUrl?: string;
+};
+export type ArcActionRouteHandler = (request: unknown, response?: unknown) => Promise<Response | unknown>;
+export type ArcExecutor = {
+    handleAction: <TActions extends ArcActionDefinitions>(actions: TActions, handlers: ArcActionHandlers<TActions>, options?: HandleActionOptions) => ArcActionRouteHandler;
+    verify: (request: unknown, options?: HandleActionOptions) => Promise<ArcRequestVerificationResult>;
+};
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type ArcDeveloperClientOptions = {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: FetchLike;
+    orgId?: string;
+    sessionCookie?: string;
+};
+export type ArcAgentClientOptions = {
+    agentToken?: string;
+    baseUrl?: string;
+    fetch?: FetchLike;
+};
+export type ArcAgentRuntimeOptions = {
+    agentToken?: string;
+    apiUrl?: string;
+    fetch?: FetchLike;
+};
+export type ArcRequestOptions = {
+    headers?: Record<string, string>;
+    retrySafeGet?: boolean;
+};
+export type SyncActionsOptions = {
+    appId?: string;
+    baseUrl?: string;
+    client?: ArcDeveloperClient;
+    dryRun?: boolean;
+    sessionCookie?: string;
+};
+export type ArcDelegationActionInput = Record<string, ArcDefaultDecision> | Array<{
+    action_id?: string;
+    action_key?: string;
+    decision: ArcDefaultDecision;
+    key?: string;
+}>;
+export type ArcDelegationInput = {
+    agent_id: string;
+    app_id: string;
+    actions: ArcDelegationActionInput;
+    expires_at?: string | null;
+    label?: string | null;
+    name?: string | null;
+};
+export type ArcDelegationUpdateInput = {
+    actions?: ArcDelegationActionInput;
+    expires_at?: string | null;
+    label?: string | null;
+    name?: string | null;
+};
+export type ArcAuditExportFormat = "bundle" | "csv" | "jsonl";
+export type ArcAuditFilters = {
+    action_id?: string;
+    action_key?: string;
+    actor_id?: string;
+    agent_id?: string;
+    app_id?: string;
+    approval_id?: string;
+    decision?: ArcDefaultDecision;
+    delegation_id?: string;
+    event_type?: string;
+    from?: string;
+    invocation_id?: string;
+    status?: string;
+    to?: string;
+    user_id?: string;
+};
+export type ArcAuditExportInput = ArcAuditFilters & {
+    filters?: ArcAuditFilters;
+    format?: ArcAuditExportFormat;
+    limit?: number;
+    offset?: number;
+};
+export type ArcOrgInviteInput = {
+    email: string;
+    name?: string | null;
+    role: "admin" | "developer" | "owner" | "viewer";
+};
+export type ArcAgentRuntimeAgent = {
+    active_delegations_count?: number;
+    created_at: string;
+    device_name: string | null;
+    display_name: string | null;
+    environment: string;
+    id: string;
+    labels: string[];
+    name: string;
+    owner_user_id: string;
+    status: "active" | "disabled" | "revoked";
+    type: "browser" | "cloud" | "custom" | "local" | "mcp";
+    updated_at: string;
+};
+export type ArcAgentRuntimeApp = {
+    arc_verification_status: "internal" | "official" | "pending" | "unverified" | "verified";
+    delegation?: {
+        expires_at: string | null;
+        id: string;
+        status: "active" | "expired" | "revoked";
+    };
+    delegation_id?: string;
+    delegation_status?: "active" | "expired" | "revoked";
+    description: string | null;
+    docs_url: string | null;
+    grant_id: string;
+    granted_action_count: number;
+    id: string;
+    name: string;
+    slug: string;
+    supported_transports: string[];
+};
+export type ArcAgentRuntimeAction = {
+    app_id: string;
+    decision: ArcDefaultDecision;
+    default_decision: ArcDefaultDecision;
+    delegation_id?: string;
+    description: string | null;
+    id: string;
+    input_schema: JsonObject;
+    key: string;
+    name: string;
+    output_schema?: JsonObject | null;
+    policy_id: string;
+    risk_level: ArcRiskLevel;
+    tags?: string[];
+};
+export type ArcAgentRuntimeGrant = {
+    actions: ArcAgentRuntimeAction[];
+    app: ArcAgentRuntimeApp;
+    id: string;
+};
+export type ArcAgentRuntimeInvokeOptions = {
+    idempotencyKey?: string;
+};
+export type ArcAgentRuntimeInvocationResult = {
+    approval_id: string | null;
+    decision: "allow";
+    idempotency_key: string;
+    invocation_id: string | null;
+    raw: unknown;
+    result: unknown;
+    status: "executed" | "queued";
+} | {
+    approval_id: string | null;
+    decision: "ask";
+    idempotency_key: string;
+    invocation_id: string | null;
+    raw: unknown;
+    result: null;
+    status: "pending_approval";
+} | {
+    approval_id: null;
+    decision: "block";
+    idempotency_key: string;
+    invocation_id: string | null;
+    raw: unknown;
+    result: null;
+    status: "blocked";
+} | {
+    approval_id: null;
+    decision: string | null;
+    error: {
+        code: string;
+        message: string;
+        status?: number;
+    };
+    idempotency_key: string;
+    invocation_id: string | null;
+    raw: unknown;
+    result: null;
+    status: "error";
+};
+export declare class ArcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ArcValidationError extends ArcError {
+    constructor(code: string, message: string);
+}
+export declare class ArcActionError extends ArcError {
+    readonly statusCode: number;
+    constructor(statusCode: number, code: string, message: string);
+}
+export declare class ArcHttpError extends ArcError {
+    readonly status: number;
+    readonly responseBody: unknown;
+    constructor(status: number, code: string, message: string, responseBody: unknown);
+}
+export declare class ArcRequestVerificationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function defineActions<TActions extends ArcActionDefinitions>(actions: TActions): TActions;
+export declare function createActionSyncPayload<TActions extends ArcActionDefinitions>(actions: TActions): ArcActionSyncPayload;
+export declare function syncActions<TActions extends ArcActionDefinitions>(actions: TActions, options?: SyncActionsOptions): Promise<ArcActionSyncPayload | unknown>;
+export declare function handleAction<TActions extends ArcActionDefinitions>(actions: TActions, handlers: ArcActionHandlers<TActions>, options?: HandleActionOptions): ArcActionRouteHandler;
+export declare function createArcExecutor(options?: HandleActionOptions): ArcExecutor;
+export declare function verifyArcRequest(request: ArcRequestLike, options: VerifyArcRequestOptions): Promise<ArcRequestVerificationResult>;
+export declare function verifyArcSignature(request: ArcRequestLike, options: VerifyArcRequestOptions): Promise<ArcRequestVerificationResult>;
+export declare function verifyArcExecution(request: ArcRequestLike, options: VerifyArcExecutionOptions): Promise<ArcRequestVerificationResult>;
+export declare function verifyArcAuthorityToken(token: string, options: VerifyArcAuthorityTokenOptions): Promise<ArcAuthorityVerificationResult>;
+export declare function requireArcAuthority(token: string, options: RequireArcAuthorityOptions): Promise<ArcAuthorityClaims>;
+export declare function createArcAuthorityMiddleware(options: ArcAuthorityMiddlewareOptions): (request: unknown, response: unknown, next?: (error?: unknown) => void) => Promise<any>;
+export declare function introspectArcAuthority(input: ArcAuthorityIntrospectionInput): Promise<ArcAuthorityIntrospectionResult>;
+export declare function verifyArcDelegation(payload: ArcExecutionRequestBody, options?: VerifyArcDelegationOptions): true;
+export declare function validateArcInvocation(payload: ArcExecutionRequestBody, options?: ValidateArcInvocationOptions): Promise<true>;
+export declare function createMemoryNonceStore(): ArcNonceReplayStore;
+export declare class ArcDeveloperClient {
+    readonly options: ArcDeveloperClientOptions;
+    private readonly fetchImpl;
+    private sessionCookie;
+    constructor(options?: ArcDeveloperClientOptions);
+    get cookie(): string | null;
+    setCookie(cookie: string | null): void;
+    devLogin(input: {
+        email: string;
+        name?: string | null;
+    }): Promise<unknown>;
+    logout(): Promise<unknown>;
+    me(): Promise<unknown>;
+    listOrgs(): Promise<unknown>;
+    getCurrentOrg(): Promise<unknown>;
+    listOrgMembers(): Promise<unknown>;
+    inviteOrgMember(input: ArcOrgInviteInput): Promise<unknown>;
+    createApp(input: {
+        app_url?: string | null;
+        auth_requirements?: JsonObject;
+        category?: string;
+        description?: string | null;
+        docs_url?: string | null;
+        execute_url: string;
+        logo_url?: string | null;
+        manifest_version?: string;
+        name: string;
+        slug: string;
+        support_url?: string | null;
+        supported_transports?: string[];
+        verification_status?: string;
+        visibility?: "org" | "private" | "public";
+    }): Promise<unknown>;
+    createAppFromManifest(input: JsonObject): Promise<unknown>;
+    listApps(): Promise<unknown>;
+    getApp(appId: string): Promise<unknown>;
+    createAppApiKey(appId: string, input?: {
+        name?: string;
+    }): Promise<unknown>;
+    listAppApiKeys(appId: string): Promise<unknown>;
+    revokeAppApiKey(appId: string, keyId: string): Promise<unknown>;
+    rotateAppApiKey(appId: string, keyId: string, input?: {
+        name?: string;
+    }): Promise<unknown>;
+    syncActions(appId: string, actions: ArcActionDefinitions | ArcActionSyncItem[]): Promise<unknown>;
+    createAppConnection(input: {
+        app_id: string;
+        app_user_id: string;
+    }): Promise<unknown>;
+    createDevAgentToken(input: {
+        agent_type: string;
+        display_name?: string | null;
+    }): Promise<unknown>;
+    registerAgent(input: {
+        device_name?: string | null;
+        environment?: string;
+        expires_in_seconds?: number;
+        labels?: string[];
+        name: string;
+        non_expiring?: boolean;
+        public_key?: string | null;
+        type: "browser" | "cloud" | "custom" | "local" | "mcp";
+    }): Promise<unknown>;
+    listAgents(): Promise<unknown>;
+    getAgent(agentId: string): Promise<unknown>;
+    updateAgent(agentId: string, input: Record<string, unknown>): Promise<unknown>;
+    revokeAgent(agentId: string): Promise<unknown>;
+    regenerateAgentToken(agentId: string, input?: {
+        expires_in_seconds?: number;
+        non_expiring?: boolean;
+    }): Promise<unknown>;
+    listAgentGrants(agentId: string): Promise<unknown>;
+    putAgentGrant(agentId: string, appId: string, actions: Record<string, ArcDefaultDecision>): Promise<unknown>;
+    listDelegations(): Promise<unknown>;
+    getDelegation(delegationId: string): Promise<unknown>;
+    createDelegation(input: ArcDelegationInput): Promise<unknown>;
+    updateDelegationPermissions(delegationId: string, input: ArcDelegationUpdateInput): Promise<unknown>;
+    revokeDelegation(delegationId: string, input?: {
+        reason?: string | null;
+    }): Promise<unknown>;
+    listDelegationAudit(delegationId: string): Promise<unknown>;
+    listRegistryApps(): Promise<unknown>;
+    getRegistryApp(appId: string): Promise<unknown>;
+    listRegistryAppActions(appId: string): Promise<unknown>;
+    getRegistryAppManifest(appId: string): Promise<unknown>;
+    listApprovals(): Promise<unknown>;
+    getApproval(approvalId: string): Promise<unknown>;
+    approveApproval(approvalId: string): Promise<unknown>;
+    denyApproval(approvalId: string): Promise<unknown>;
+    tailAudit(input?: {
+        limit?: number;
+    }): Promise<unknown>;
+    exportAudit(input?: ArcAuditExportInput): Promise<unknown>;
+    createAuditExport(input?: ArcAuditExportInput): Promise<unknown>;
+    getAuditExport(exportId: string): Promise<unknown>;
+    verifyAudit(input?: ArcAuditExportInput): Promise<unknown>;
+    getAuditTimeline(input?: ArcAuditExportInput): Promise<unknown>;
+    getJwks(): Promise<unknown>;
+    getAuthorityMetadata(): Promise<unknown>;
+    introspectAuthority(input: {
+        invocation_id?: string;
+        signed_execution_id?: string;
+        token?: string;
+    }): Promise<unknown>;
+    request<T = unknown>(method: string, path: string, body?: unknown, options?: ArcRequestOptions): Promise<T>;
+    private authHeaders;
+}
+export declare class ArcAgentRuntimeClient {
+    readonly options: ArcAgentRuntimeOptions;
+    private readonly fetchImpl;
+    constructor(options?: ArcAgentRuntimeOptions);
+    me(): Promise<ArcAgentRuntimeAgent>;
+    listApps(): Promise<ArcAgentRuntimeApp[]>;
+    listActions(appId: string): Promise<ArcAgentRuntimeAction[]>;
+    getAvailableActions(): Promise<ArcAgentRuntimeAction[]>;
+    createActionRequest(input: {
+        action: string;
+        amount?: number;
+        app_id?: string;
+        app_slug?: string;
+        evidence?: Array<Record<string, unknown>>;
+        idempotency_key?: string;
+        reason?: string;
+        resource?: string;
+        resource_id?: string;
+        resource_type?: string;
+    }): Promise<unknown>;
+    pollActionRequest(actionRequestId: string): Promise<unknown>;
+    listGrants(): Promise<ArcAgentRuntimeGrant[]>;
+    invoke(appId: string, actionKey: string, input?: JsonObject, options?: ArcAgentRuntimeInvokeOptions): Promise<ArcAgentRuntimeInvocationResult>;
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+}
+export declare function createArcAgentRuntime(options: ArcAgentRuntimeOptions): ArcAgentRuntimeClient;
+export declare class ArcAgentClient {
+    readonly options: ArcAgentClientOptions;
+    private readonly fetchImpl;
+    constructor(options?: ArcAgentClientOptions);
+    invoke(input: {
+        action_key: string;
+        app_id?: string;
+        app_slug?: string;
+        idempotency_key?: string;
+        input?: JsonObject;
+    }): Promise<unknown>;
+    listActions(input: {
+        app_id?: string;
+        app_slug?: string;
+    }): Promise<unknown>;
+    createActionRequest(input: {
+        action: string;
+        amount?: number;
+        app_id?: string;
+        app_slug?: string;
+        evidence?: Array<Record<string, unknown>>;
+        idempotency_key?: string;
+        reason?: string;
+        resource?: string;
+        resource_id?: string;
+        resource_type?: string;
+    }): Promise<unknown>;
+    pollActionRequest(actionRequestId: string): Promise<unknown>;
+    getInvocation(invocationId: string): Promise<unknown>;
+    me(): Promise<ArcAgentRuntimeAgent>;
+    listApps(): Promise<ArcAgentRuntimeApp[]>;
+    listGrants(): Promise<ArcAgentRuntimeGrant[]>;
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+}
+export declare const arc: {
+    ArcAgentClient: typeof ArcAgentClient;
+    ArcAgentRuntimeClient: typeof ArcAgentRuntimeClient;
+    ArcDeveloperClient: typeof ArcDeveloperClient;
+    createActionSyncPayload: typeof createActionSyncPayload;
+    createArcAuthorityMiddleware: typeof createArcAuthorityMiddleware;
+    createArcExecutor: typeof createArcExecutor;
+    createArcAgentRuntime: typeof createArcAgentRuntime;
+    createMemoryNonceStore: typeof createMemoryNonceStore;
+    defineActions: typeof defineActions;
+    handleAction: typeof handleAction;
+    introspectArcAuthority: typeof introspectArcAuthority;
+    requireArcAuthority: typeof requireArcAuthority;
+    syncActions: typeof syncActions;
+    validateArcInvocation: typeof validateArcInvocation;
+    verifyArcDelegation: typeof verifyArcDelegation;
+    verifyArcExecution: typeof verifyArcExecution;
+    verifyArcSignature: typeof verifyArcSignature;
+    verifyArcAuthorityToken: typeof verifyArcAuthorityToken;
+    verifyArcRequest: typeof verifyArcRequest;
+};
+export declare function createSlug(value: string): string;