@zcloak/ai-agent 1.0.0

package/dist/types/common.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Common utility type definitions
+ *
+ * Contains public types for command line arguments, PoW results, MANIFEST, etc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=common.js.map

package/dist/types/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/types/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Configuration type definitions
+ *
+ * Defines interfaces for canister IDs and application config.
+ */
+/** Canister ID pair */
+export interface CanisterIds {
+    /** Registry canister ID */
+    registry: string;
+    /** Signatures canister ID */
+    signatures: string;
+}
+/** Full application configuration */
+export interface AppConfig {
+    /** Canister IDs */
+    canisterIds: CanisterIds;
+    /** PoW required leading zeros count */
+    pow_zeros: number;
+    /** Agent binding page URL */
+    bind_url: string;
+    /** Agent profile page URL prefix */
+    profile_url: string;
+    /** 2FA verification page URL */
+    twofa_url: string;
+    /** Event view page URL prefix (appended with event ID to form the full URL) */
+    event_url: string;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/types/config.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Configuration type definitions
+ *
+ * Defines interfaces for canister IDs and application config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/types/registry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AUTO-GENERATED from idl.ts — DO NOT EDIT MANUALLY
+ *
+ * Run `npm run generate-types` to regenerate this file.
+ * Source: registryIdlFactory in src/idl.ts
+ * Generated: 2026-03-04T08:49:52.875Z
+ *
+ * These types are derived from the Candid IDL definitions and correspond to
+ * the canister's runtime interface. Edit idl.ts to change type definitions.
+ */
+import type { Principal } from '@dfinity/principal';
+import type { ActorMethod } from '@dfinity/agent';
+import type { CandidOpt } from './sign-event';
+/** Position record — position information in the registry canister */
+export interface Position {
+    is_human: boolean;
+    connection_list: Principal[];
+}
+/** AI profile record */
+export interface AiProfile {
+    position: CandidOpt<Position>;
+}
+/** User profile record */
+export interface UserProfile {
+    username: string;
+    passkey_name: string[];
+    ai_profile: CandidOpt<AiProfile>;
+    principal_id: CandidOpt<string>;
+}
+/** Registration success result */
+export interface RegisterResult {
+    username: string;
+}
+/** 2FA verification record — tracks a pending or completed 2FA request */
+export interface TwoFARecord {
+    request_timestamp: bigint;
+    content: string;
+    confirm_timestamp: CandidOpt<bigint>;
+    confirm_owner: CandidOpt<string>;
+    caller: string;
+    owner_list: string[];
+}
+/** Return type for canister method */
+export type AgentPrepareBondResult = {
+    Ok: string;
+} | {
+    Err: string;
+};
+/** Return type for canister method */
+export type Prepare2faInfoResult = {
+    Ok: string;
+} | {
+    Err: string;
+};
+/** Return type for canister method */
+export type RegisterAgentResult = {
+    Ok: RegisterResult;
+} | {
+    Err: string;
+};
+/** Registry canister service interface */
+export interface RegistryService {
+    agent_prepare_bond: ActorMethod<[string], AgentPrepareBondResult>;
+    get_user_principal: ActorMethod<[string], CandidOpt<Principal>>;
+    get_username_by_principal: ActorMethod<[string], CandidOpt<string>>;
+    prepare_2fa_info: ActorMethod<[string], Prepare2faInfoResult>;
+    query_2fa_result_by_challenge: ActorMethod<[string], CandidOpt<TwoFARecord>>;
+    register_agent: ActorMethod<[string], RegisterAgentResult>;
+    user_profile_get: ActorMethod<[string], CandidOpt<UserProfile>>;
+    user_profile_get_by_principal: ActorMethod<[string], CandidOpt<UserProfile>>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/registry.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * AUTO-GENERATED from idl.ts — DO NOT EDIT MANUALLY
+ *
+ * Run `npm run generate-types` to regenerate this file.
+ * Source: registryIdlFactory in src/idl.ts
+ * Generated: 2026-03-04T08:49:52.875Z
+ *
+ * These types are derived from the Candid IDL definitions and correspond to
+ * the canister's runtime interface. Edit idl.ts to change type definitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=registry.js.map

package/dist/types/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/types/registry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/dist/types/sign-event.d.ts

@@ -0,0 +1,134 @@
+/**
+ * AUTO-GENERATED from idl.ts — DO NOT EDIT MANUALLY
+ *
+ * Run `npm run generate-types` to regenerate this file.
+ * Source: signIdlFactory in src/idl.ts
+ * Generated: 2026-03-04T08:49:52.875Z
+ *
+ * These types are derived from the Candid IDL definitions and correspond to
+ * the canister's runtime interface. Edit idl.ts to change type definitions.
+ */
+import type { Principal } from '@dfinity/principal';
+import type { ActorMethod } from '@dfinity/agent';
+/** Candid opt type representation: [] means null, [T] means has value */
+export type CandidOpt<T> = [] | [T];
+/** SignEvent — sign event record returned by canister */
+export interface SignEvent {
+    id: string;
+    content: CandidOpt<string>;
+    counter: CandidOpt<number>;
+    ai_id: string;
+    kind: number;
+    content_hash: string;
+    tags: CandidOpt<string[][]>;
+    created_at: bigint;
+}
+/** SignParm variant — signing parameter types (one-of union) */
+export type SignParm = {
+    Kind13PrivateContract: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind12PublicContract: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind10JobRequest: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind1IdentityProfile: {
+        content: string;
+    };
+} | {
+    Kind5PrivatePost: {
+        ibe_identity: string;
+        encrypted_content: number[];
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind8MediaAsset: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind6Interaction: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind9ServiceListing: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind4PublicPost: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind7ContactList: {
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind3SimpleAgreement: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind15GeneralAttestation: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind2IdentityVerification: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind14Review: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+} | {
+    Kind11DocumentSignature: {
+        content: string;
+        tags: CandidOpt<string[][]>;
+    };
+};
+/** Return type for canister method */
+export type AgentSignResult = {
+    Ok: SignEvent;
+} | {
+    Err: string;
+};
+/** Backward-compatible alias for agent_sign return type */
+export type SignResult = AgentSignResult;
+/** Signatures canister service interface — all callable canister methods */
+export interface SignService {
+    agent_sign: ActorMethod<[SignParm, string], AgentSignResult>;
+    derive_vetkey: ActorMethod<[string, number[]], number[]>;
+    fetch_events_by_counter: ActorMethod<[number, number], SignEvent[]>;
+    fetch_user_sign: ActorMethod<[Principal, number, number], [number, SignEvent[]]>;
+    get_all_sign_events: ActorMethod<[], SignEvent[]>;
+    get_counter: ActorMethod<[], number>;
+    get_ibe_public_key: ActorMethod<[], number[]>;
+    get_kind1_event_by_principal: ActorMethod<[string], CandidOpt<SignEvent>>;
+    get_kind5_decryption_key: ActorMethod<[string, number[]], {
+        encrypted_key: number[];
+        ciphertext: number[];
+        ibe_identity: string;
+    }>;
+    get_sign_event_by_id: ActorMethod<[string], CandidOpt<SignEvent>>;
+    get_user_latest_sign_event_id: ActorMethod<[Principal], string>;
+    greet: ActorMethod<[string], string>;
+    mcp_sign: ActorMethod<[Principal, SignParm], SignEvent>;
+    sign: ActorMethod<[SignParm], SignEvent>;
+    verify_file_hash: ActorMethod<[string], SignEvent[]>;
+    verify_message: ActorMethod<[string], SignEvent[]>;
+    verify_msg_hash: ActorMethod<[string], SignEvent[]>;
+}
+//# sourceMappingURL=sign-event.d.ts.map

package/dist/types/sign-event.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * AUTO-GENERATED from idl.ts — DO NOT EDIT MANUALLY
+ *
+ * Run `npm run generate-types` to regenerate this file.
+ * Source: signIdlFactory in src/idl.ts
+ * Generated: 2026-03-04T08:49:52.875Z
+ *
+ * These types are derived from the Candid IDL definitions and correspond to
+ * the canister's runtime interface. Edit idl.ts to change type definitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=sign-event.js.map

package/dist/types/sign-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-event.js","sourceRoot":"","sources":["../../src/types/sign-event.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/dist/utils.d.ts

@@ -0,0 +1,113 @@
+/**
+ * zCloak.ai Common Utilities
+ *
+ * Provides PoW computation, file hashing, argument parsing, formatted output, and more.
+ * All other scripts depend on this module.
+ */
+import type { ParsedArgs, PowResult, ManifestOptions, ManifestResult, ManifestEntry, ManifestVerifyResult } from './types/common';
+import type { SignEvent, SignResult } from './types/sign-event';
+export declare function computePow(base: string, zeros?: number): PowResult;
+/**
+ * Parse command line arguments into a structured object.
+ * Supports both --key=value and --flag formats.
+ * Positional arguments (not starting with --) are placed in _args array in order.
+ *
+ * When called with an explicit argv array, uses that instead of process.argv.
+ * The first two elements (node path and script path) are always skipped,
+ * matching the process.argv convention.
+ *
+ * @param argv - Optional explicit argument array (defaults to process.argv)
+ */
+export declare function parseArgs(argv?: string[]): ParsedArgs;
+/**
+ * Parse --tags argument into a tag array
+ * Format: "t:crypto,sub:web3,m:alice_id"
+ */
+export declare function parseTags(tagsStr: string | boolean | string[] | undefined): string[][];
+/**
+ * Compute SHA256 hash of a file (pure Node.js implementation, no shell dependency)
+ * @param filePath - File path
+ * @returns 64-character hex hash value
+ * @throws {Error} If the file cannot be read
+ */
+export declare function hashFile(filePath: string): string;
+/**
+ * Get file size (bytes)
+ * @throws {Error} If the file cannot be stat'd
+ */
+export declare function getFileSize(filePath: string): number;
+/**
+ * Return MIME type based on file path
+ */
+export declare function getMimeType(filePath: string): string;
+/**
+ * Recursively list all files in a directory (excluding MANIFEST.sha256, .git, node_modules)
+ * @param dir - Directory path
+ * @param prefix - Path prefix (for recursion)
+ * @returns Sorted list of relative paths
+ */
+export declare function listFiles(dir: string, prefix?: string): string[];
+/**
+ * Generate MANIFEST.sha256 file (with metadata header)
+ * Format compatible with GNU sha256sum, metadata represented as # comment lines
+ *
+ * This version uses pure Node.js implementation, no shell command dependency.
+ * The author field is obtained via identity.ts; left empty if identity cannot be loaded.
+ */
+export declare function generateManifest(folderPath: string, options?: ManifestOptions): ManifestResult;
+/**
+ * Parse MANIFEST.sha256 file content into structured entries.
+ *
+ * Skips comment lines (starting with #) and empty lines.
+ * Each valid line must match: <64-hex-hash> <whitespace> <path>
+ * Non-empty non-comment lines that don't match this format cause an error
+ * (strict mode — prevents silently ignoring corrupted MANIFEST content).
+ *
+ * @param manifestContent - Full text content of the MANIFEST.sha256 file
+ * @returns Array of parsed ManifestEntry objects
+ * @throws {Error} If a non-empty non-comment line has invalid format
+ */
+export declare function parseManifestEntries(manifestContent: string): ManifestEntry[];
+/**
+ * Verify file integrity against MANIFEST entries.
+ *
+ * Parses the MANIFEST content, then checks each listed file:
+ * - If the file does not exist → { passed: false, reason: 'not_found' }
+ * - If the file hash doesn't match → { passed: false, reason: 'hash_mismatch' }
+ * - If the hash matches → { passed: true }
+ *
+ * Returns structured results; the caller decides how to format output.
+ *
+ * @param manifestContent - MANIFEST.sha256 file content
+ * @param basePath - Absolute path of the folder containing the files
+ * @returns Array of verification results, one per file entry
+ * @throws {Error} If the MANIFEST format is invalid
+ */
+export declare function verifyManifestEntries(manifestContent: string, basePath: string): ManifestVerifyResult[];
+/**
+ * Format a SignEvent object into readable text
+ * Candid opt types are represented as [] | [value] in JS
+ */
+export declare function formatSignEvent(event: SignEvent): string;
+/**
+ * Format a SignEvent array
+ */
+export declare function formatSignEvents(events: SignEvent[]): string;
+/**
+ * Build a full event view URL from an event ID.
+ * Uses the configured event_url prefix from config.
+ * @param eventId - The unique event ID (sha256 hash)
+ * @returns Full URL to view the event on the website
+ */
+export declare function buildEventUrl(eventId: string): string;
+/**
+ * Format agent_sign return value (Ok/Err variant).
+ * On success, appends a "View:" line with the event URL so the agent
+ * can present a clickable link to the user.
+ */
+export declare function formatSignResult(result: SignResult): string;
+/**
+ * Format opt text type
+ */
+export declare function formatOptText(optText: [] | [string]): string;
+//# sourceMappingURL=utils.d.ts.map