@vouchagents/client 0.1.0

package/dist/vault/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../src/vault/vault.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@vouchagents/client",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@vouchagents/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/consent.ts

@@ -0,0 +1,83 @@
+import {
+  createConsentToken,
+  canonicalHash,
+  SensitiveString,
+  type AgentSignupDiscovery,
+} from "@vouchagents/protocol";
+import type { Vault } from "./vault/vault.js";
+
+export interface ConsentRequest {
+  site: AgentSignupDiscovery["branding"] & { url: string };
+  requestedFields: {
+    required: Array<{ field: string }>;
+    optional?: Array<{ field: string }>;
+  };
+  nonce: string;
+  siteEndpoint: string;
+  agentId?: string;
+}
+
+export interface ConsentApproved {
+  approved: true;
+  token: string;
+  fields: Record<string, string>;
+}
+
+export interface ConsentDenied {
+  approved: false;
+  reason: "user_denied" | "timeout" | "missing_fields" | "vault_locked";
+}
+
+export type ConsentResult = ConsentApproved | ConsentDenied;
+
+export class ConsentManager {
+  constructor(private vault: Vault) {}
+
+  /** Request consent for a signup. Checks for matching auto-approve policies first. */
+  async requestConsent(request: ConsentRequest): Promise<ConsentResult> {
+    if (!this.vault.isUnlocked()) {
+      return { approved: false, reason: "vault_locked" };
+    }
+
+    const requiredFieldNames = request.requestedFields.required.map(
+      (f) => f.field,
+    );
+
+    // Check for matching auto-approve policy
+    const policy = await this.vault.findMatchingPolicy(
+      request.site.url,
+      requiredFieldNames,
+    );
+
+    // Get the field values
+    const fields = await this.vault.getFieldsRaw(requiredFieldNames);
+
+    // Check all required fields are available
+    const missing = requiredFieldNames.filter((f) => !fields[f]);
+    if (missing.length > 0) {
+      return { approved: false, reason: "missing_fields" };
+    }
+
+    // Create consent token
+    const keyPair = this.vault.getKeyPair();
+    const token = await createConsentToken({
+      userKeyPair: keyPair,
+      agentId: request.agentId ?? "unknown-agent",
+      audience: request.site.url,
+      nonce: request.nonce,
+      fields: requiredFieldNames,
+      data: fields,
+      purpose: "account_creation",
+      consentMode: policy ? "pre_authorized" : "explicit",
+      siteEndpoint: request.siteEndpoint,
+      policyId: policy?.id,
+    });
+
+    // Decrement policy uses if auto-approved
+    if (policy && policy.remainingUses !== undefined) {
+      policy.remainingUses--;
+    }
+
+    return { approved: true, token, fields };
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// Vault
+export {
+  Vault,
+  FileStorage,
+  LocalStorageBackend,
+  MemoryStorage,
+  defaultVaultPath,
+  type StorageBackend,
+  type VaultData,
+  type SignupHistoryEntry,
+  type PolicyEntry,
+} from "./vault/index.js";
+
+// Consent
+export {
+  ConsentManager,
+  type ConsentRequest,
+  type ConsentResult,
+  type ConsentApproved,
+  type ConsentDenied,
+} from "./consent.js";
+
+// Password
+export { generatePassword, type PasswordPolicy } from "./password.js";

package/src/password.ts

@@ -0,0 +1,79 @@
+import { SensitiveString } from "@vouchagents/protocol";
+
+export interface PasswordPolicy {
+  minLength?: number;
+  requireUppercase?: boolean;
+  requireLowercase?: boolean;
+  requireNumbers?: boolean;
+  requireSymbols?: boolean;
+}
+
+const DEFAULT_POLICY: Required<PasswordPolicy> = {
+  minLength: 20,
+  requireUppercase: true,
+  requireLowercase: true,
+  requireNumbers: true,
+  requireSymbols: true,
+};
+
+const UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+const NUMBERS = "0123456789";
+const SYMBOLS = "!@#$%^&*()-_=+[]{}|;:,.<>?";
+
+/** Generate a cryptographically random password meeting the given policy. */
+export function generatePassword(policy?: PasswordPolicy): SensitiveString {
+  const p = { ...DEFAULT_POLICY, ...policy };
+  const length = Math.max(p.minLength, 12);
+
+  let charset = "";
+  const required: string[] = [];
+
+  if (p.requireUppercase) {
+    charset += UPPERCASE;
+    required.push(randomChar(UPPERCASE));
+  }
+  if (p.requireLowercase) {
+    charset += LOWERCASE;
+    required.push(randomChar(LOWERCASE));
+  }
+  if (p.requireNumbers) {
+    charset += NUMBERS;
+    required.push(randomChar(NUMBERS));
+  }
+  if (p.requireSymbols) {
+    charset += SYMBOLS;
+    required.push(randomChar(SYMBOLS));
+  }
+
+  if (charset.length === 0) {
+    charset = UPPERCASE + LOWERCASE + NUMBERS;
+  }
+
+  // Fill remaining length with random chars from the full charset
+  const remaining = length - required.length;
+  const chars = [...required];
+  for (let i = 0; i < remaining; i++) {
+    chars.push(randomChar(charset));
+  }
+
+  // Shuffle to avoid predictable positions for required chars
+  shuffle(chars);
+
+  return new SensitiveString(chars.join(""));
+}
+
+function randomChar(charset: string): string {
+  const array = new Uint32Array(1);
+  globalThis.crypto.getRandomValues(array);
+  return charset[array[0] % charset.length];
+}
+
+function shuffle(array: string[]): void {
+  for (let i = array.length - 1; i > 0; i--) {
+    const randomValues = new Uint32Array(1);
+    globalThis.crypto.getRandomValues(randomValues);
+    const j = randomValues[0] % (i + 1);
+    [array[i], array[j]] = [array[j], array[i]];
+  }
+}

package/src/vault/index.ts

@@ -0,0 +1,9 @@
+export { Vault } from "./vault.js";
+export type { VaultData, SignupHistoryEntry, PolicyEntry } from "./vault.js";
+export {
+  FileStorage,
+  LocalStorageBackend,
+  MemoryStorage,
+  defaultVaultPath,
+  type StorageBackend,
+} from "./storage.js";

package/src/vault/storage.ts

@@ -0,0 +1,80 @@
+/** Storage backend interface. The vault doesn't care where the encrypted blob lives. */
+export interface StorageBackend {
+  read(): Promise<string | null>;
+  write(data: string): Promise<void>;
+  exists(): Promise<boolean>;
+}
+
+/** File-based storage (~/.agent-signup/vault.json). Works in Node.js/Bun. */
+export class FileStorage implements StorageBackend {
+  constructor(private path: string) {}
+
+  async read(): Promise<string | null> {
+    try {
+      const fs = await import("node:fs/promises");
+      return await fs.readFile(this.path, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  async write(data: string): Promise<void> {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    await fs.mkdir(path.dirname(this.path), { recursive: true });
+    await fs.writeFile(this.path, data, "utf-8");
+  }
+
+  async exists(): Promise<boolean> {
+    try {
+      const fs = await import("node:fs/promises");
+      await fs.access(this.path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** localStorage-based storage. Works in browsers. */
+export class LocalStorageBackend implements StorageBackend {
+  constructor(private key: string = "agent-signup:vault") {}
+
+  async read(): Promise<string | null> {
+    return globalThis.localStorage?.getItem(this.key) ?? null;
+  }
+
+  async write(data: string): Promise<void> {
+    globalThis.localStorage?.setItem(this.key, data);
+  }
+
+  async exists(): Promise<boolean> {
+    return globalThis.localStorage?.getItem(this.key) !== null;
+  }
+}
+
+/** In-memory storage for testing. */
+export class MemoryStorage implements StorageBackend {
+  private data: string | null = null;
+
+  async read(): Promise<string | null> {
+    return this.data;
+  }
+
+  async write(data: string): Promise<void> {
+    this.data = data;
+  }
+
+  async exists(): Promise<boolean> {
+    return this.data !== null;
+  }
+}
+
+/** Get the default vault file path. */
+export function defaultVaultPath(): string {
+  const home =
+    typeof process !== "undefined"
+      ? process.env.HOME || process.env.USERPROFILE || "."
+      : ".";
+  return `${home}/.agent-signup/vault.json`;
+}

package/src/vault/vault.ts

@@ -0,0 +1,343 @@
+import {
+  generateKeyPair,
+  deriveEncryptionKey,
+  encrypt,
+  decrypt,
+  generateSalt,
+  base64urlEncode,
+  base64urlDecode,
+  type KeyPair,
+  SensitiveString,
+} from "@vouchagents/protocol";
+import type { StorageBackend } from "./storage.js";
+
+export interface VaultData {
+  fields: Record<string, string>;
+  passwords: Record<string, string>;
+  history: SignupHistoryEntry[];
+  policies: PolicyEntry[];
+  custom: Record<string, string>;
+}
+
+export interface SignupHistoryEntry {
+  id: string;
+  site: string;
+  siteUrl: string;
+  fields: string[];
+  consentMode: "explicit" | "pre_authorized" | "manual";
+  status: "pending" | "verified" | "expired" | "failed" | "user_directed";
+  timestamp: string;
+}
+
+export interface PolicyEntry {
+  id: string;
+  name: string;
+  scopes: string[];
+  allowedOrigins: string[];
+  allowedFields: string[];
+  maxUses?: number;
+  remainingUses?: number;
+  expiresAt: string;
+  createdAt: string;
+}
+
+interface VaultFile {
+  version: 1;
+  kdf: {
+    algorithm: "pbkdf2";
+    iterations: number;
+    salt: string;
+  };
+  vault: string;
+  vault_iv: string;
+  signing_public_key: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export class Vault {
+  private encryptionKey: CryptoKey | null = null;
+  private keyPair: KeyPair | null = null;
+  private data: VaultData | null = null;
+  private vaultFile: VaultFile | null = null;
+  private lockedAt: number = 0;
+  private readonly autoLockMs = 15 * 60 * 1000; // 15 minutes
+
+  private constructor(private storage: StorageBackend) {}
+
+  /** Create a new vault with a passphrase. */
+  static async create(options: {
+    passphrase: string;
+    storage: StorageBackend;
+  }): Promise<Vault> {
+    const vault = new Vault(options.storage);
+    const salt = generateSalt();
+    const encryptionKey = await deriveEncryptionKey(options.passphrase, salt);
+    const keyPair = await generateKeyPair();
+
+    vault.encryptionKey = encryptionKey;
+    vault.keyPair = keyPair;
+    vault.data = {
+      fields: {},
+      passwords: {},
+      history: [],
+      policies: [],
+      custom: {},
+    };
+
+    vault.vaultFile = {
+      version: 1,
+      kdf: {
+        algorithm: "pbkdf2",
+        iterations: 600_000,
+        salt: base64urlEncode(salt),
+      },
+      vault: "", // filled on save
+      vault_iv: "",
+      signing_public_key: base64urlEncode(keyPair.publicKey),
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    vault.lockedAt = Date.now();
+    await vault.save();
+    return vault;
+  }
+
+  /** Open an existing vault with a passphrase. */
+  static async open(options: {
+    passphrase: string;
+    storage: StorageBackend;
+  }): Promise<Vault> {
+    const vault = new Vault(options.storage);
+    const raw = await options.storage.read();
+    if (!raw) {
+      throw new Error("No vault found");
+    }
+
+    const vaultFile: VaultFile = JSON.parse(raw);
+    vault.vaultFile = vaultFile;
+
+    const salt = base64urlDecode(vaultFile.kdf.salt);
+    const encryptionKey = await deriveEncryptionKey(options.passphrase, salt);
+    vault.encryptionKey = encryptionKey;
+
+    // Decrypt the vault data
+    const ciphertext = base64urlDecode(vaultFile.vault);
+    const iv = base64urlDecode(vaultFile.vault_iv);
+
+    try {
+      const decrypted = await decrypt(ciphertext, encryptionKey, iv);
+      const json = new TextDecoder().decode(decrypted);
+      const parsed = JSON.parse(json);
+      vault.data = parsed.data;
+      vault.keyPair = {
+        publicKey: base64urlDecode(vaultFile.signing_public_key),
+        privateKey: base64urlDecode(parsed.privateKey),
+        keyId: parsed.keyId,
+      };
+    } catch {
+      throw new Error("Wrong passphrase");
+    }
+
+    vault.lockedAt = Date.now();
+    return vault;
+  }
+
+  /** Check if a vault exists at the storage location. */
+  static async exists(storage: StorageBackend): Promise<boolean> {
+    return storage.exists();
+  }
+
+  // --- Field operations ---
+
+  async setField(name: string, value: string): Promise<void> {
+    this.ensureUnlocked();
+    this.data!.fields[name] = value;
+    await this.save();
+  }
+
+  async getField(name: string): Promise<SensitiveString | null> {
+    this.ensureUnlocked();
+    const value = this.data!.fields[name];
+    return value ? new SensitiveString(value) : null;
+  }
+
+  async listFields(): Promise<string[]> {
+    this.ensureUnlocked();
+    return Object.keys(this.data!.fields);
+  }
+
+  async getFieldsRaw(fieldNames: string[]): Promise<Record<string, string>> {
+    this.ensureUnlocked();
+    const result: Record<string, string> = {};
+    for (const name of fieldNames) {
+      const value = this.data!.fields[name] ?? this.data!.custom[name];
+      if (value) result[name] = value;
+    }
+    return result;
+  }
+
+  // --- Password operations ---
+
+  async setPassword(siteUrl: string, password: SensitiveString): Promise<void> {
+    this.ensureUnlocked();
+    this.data!.passwords[siteUrl] = password.unsafeUnwrap();
+    await this.save();
+  }
+
+  async getPassword(siteUrl: string): Promise<SensitiveString | null> {
+    this.ensureUnlocked();
+    const value = this.data!.passwords[siteUrl];
+    return value ? new SensitiveString(value) : null;
+  }
+
+  // --- Custom fields ---
+
+  async setCustomField(name: string, value: string): Promise<void> {
+    this.ensureUnlocked();
+    this.data!.custom[name] = value;
+    await this.save();
+  }
+
+  // --- History ---
+
+  async addHistory(entry: SignupHistoryEntry): Promise<void> {
+    this.ensureUnlocked();
+    this.data!.history.unshift(entry);
+    await this.save();
+  }
+
+  async getHistory(options?: {
+    limit?: number;
+    siteUrl?: string;
+  }): Promise<SignupHistoryEntry[]> {
+    this.ensureUnlocked();
+    let entries = this.data!.history;
+    if (options?.siteUrl) {
+      entries = entries.filter((e) => e.siteUrl === options.siteUrl);
+    }
+    if (options?.limit) {
+      entries = entries.slice(0, options.limit);
+    }
+    return entries;
+  }
+
+  // --- Policies ---
+
+  async addPolicy(policy: PolicyEntry): Promise<void> {
+    this.ensureUnlocked();
+    this.data!.policies.push(policy);
+    await this.save();
+  }
+
+  async getPolicies(): Promise<PolicyEntry[]> {
+    this.ensureUnlocked();
+    return this.data!.policies.filter(
+      (p) => new Date(p.expiresAt) > new Date(),
+    );
+  }
+
+  async removePolicy(policyId: string): Promise<void> {
+    this.ensureUnlocked();
+    this.data!.policies = this.data!.policies.filter((p) => p.id !== policyId);
+    await this.save();
+  }
+
+  async findMatchingPolicy(
+    origin: string,
+    fields: string[],
+  ): Promise<PolicyEntry | null> {
+    this.ensureUnlocked();
+    const now = new Date();
+    return (
+      this.data!.policies.find((p) => {
+        if (new Date(p.expiresAt) <= now) return false;
+        if (p.remainingUses !== undefined && p.remainingUses <= 0) return false;
+        const originMatch = p.allowedOrigins.some(
+          (o) => o === "*" || origin.includes(o),
+        );
+        if (!originMatch) return false;
+        return fields.every((f) => p.allowedFields.includes(f));
+      }) ?? null
+    );
+  }
+
+  // --- Identity ---
+
+  getIdentity(): { publicKey: string; keyId: string } {
+    this.ensureUnlocked();
+    return {
+      publicKey: base64urlEncode(this.keyPair!.publicKey),
+      keyId: this.keyPair!.keyId,
+    };
+  }
+
+  getKeyPair(): KeyPair {
+    this.ensureUnlocked();
+    return this.keyPair!;
+  }
+
+  // --- Lock/unlock ---
+
+  isUnlocked(): boolean {
+    if (!this.encryptionKey || !this.data) return false;
+    if (Date.now() - this.lockedAt > this.autoLockMs) {
+      this.lock();
+      return false;
+    }
+    return true;
+  }
+
+  lock(): void {
+    this.encryptionKey = null;
+    this.keyPair = null;
+    this.data = null;
+  }
+
+  // --- Export/import ---
+
+  async export(): Promise<string> {
+    const raw = await this.storage.read();
+    if (!raw) throw new Error("No vault to export");
+    return raw;
+  }
+
+  static async import(
+    exported: string,
+    options: { passphrase: string; storage: StorageBackend },
+  ): Promise<Vault> {
+    await options.storage.write(exported);
+    return Vault.open(options);
+  }
+
+  // --- Internal ---
+
+  private ensureUnlocked(): void {
+    if (!this.isUnlocked()) {
+      throw new Error("Vault is locked");
+    }
+    this.lockedAt = Date.now(); // reset idle timer
+  }
+
+  private async save(): Promise<void> {
+    if (!this.encryptionKey || !this.data || !this.keyPair || !this.vaultFile) {
+      throw new Error("Cannot save: vault not initialized");
+    }
+
+    const plaintext = JSON.stringify({
+      data: this.data,
+      privateKey: base64urlEncode(this.keyPair.privateKey),
+      keyId: this.keyPair.keyId,
+    });
+
+    const encoded = new TextEncoder().encode(plaintext);
+    const { ciphertext, iv } = await encrypt(encoded, this.encryptionKey);
+
+    this.vaultFile.vault = base64urlEncode(ciphertext);
+    this.vaultFile.vault_iv = base64urlEncode(iv);
+    this.vaultFile.updated_at = new Date().toISOString();
+
+    await this.storage.write(JSON.stringify(this.vaultFile, null, 2));
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src"]
+}