@opengeni/vaults-protonpass 0.0.0-stage → 3.3.0

package/src/runner.ts

@@ -0,0 +1,144 @@
+import { spawn } from "node:child_process";
+
+/** One bounded subprocess run. No shell, no inherited environment. */
+export interface ProcessRequest {
+  file: string;
+  args: readonly string[];
+  env: Readonly<Record<string, string>>;
+  cwd: string;
+  stdin?: string;
+  timeoutMs: number;
+  maxStdoutBytes: number;
+  maxStderrBytes: number;
+  signal?: AbortSignal;
+}
+
+export interface ProcessResult {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  aborted: boolean;
+  /** stdout exceeded its bound; the process was killed and stdout is incomplete. */
+  stdoutOverflow: boolean;
+  /** The binary could not be started (missing, not executable). */
+  spawnError: string | null;
+}
+
+export type ProcessRunner = (request: ProcessRequest) => Promise<ProcessResult>;
+
+const KILL_GRACE_MS = 1_000;
+
+/**
+ * Runs `file` with an argv array and an explicit environment. stdout is capped
+ * (the process is killed past the cap), stderr is truncated, and the process
+ * group is terminated on timeout or abort, so a hung CLI cannot outlive the call.
+ */
+export const runProcess: ProcessRunner = (request) =>
+  new Promise<ProcessResult>((resolve) => {
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stdoutOverflow = false;
+    let timedOut = false;
+    let aborted = false;
+    let settled = false;
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+
+    if (request.signal?.aborted) {
+      resolve({
+        exitCode: null,
+        signal: null,
+        stdout: "",
+        stderr: "",
+        timedOut: false,
+        aborted: true,
+        stdoutOverflow: false,
+        spawnError: null,
+      });
+      return;
+    }
+
+    const child = spawn(request.file, [...request.args], {
+      cwd: request.cwd,
+      env: { ...request.env },
+      shell: false,
+      detached: process.platform !== "win32",
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+
+    const terminate = () => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      const kill = (sig: NodeJS.Signals) => {
+        try {
+          if (child.pid !== undefined && process.platform !== "win32")
+            process.kill(-child.pid, sig);
+          else child.kill(sig);
+        } catch {
+          // Already gone.
+        }
+      };
+      kill("SIGTERM");
+      killTimer ??= setTimeout(() => kill("SIGKILL"), KILL_GRACE_MS);
+      killTimer.unref?.();
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      terminate();
+    }, request.timeoutMs);
+    timer.unref?.();
+    const onAbort = () => {
+      aborted = true;
+      terminate();
+    };
+    request.signal?.addEventListener("abort", onAbort, { once: true });
+
+    const finish = (
+      result: Omit<ProcessResult, "stdout" | "stderr" | "timedOut" | "aborted" | "stdoutOverflow">,
+    ) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      request.signal?.removeEventListener("abort", onAbort);
+      resolve({
+        ...result,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        timedOut,
+        aborted,
+        stdoutOverflow,
+      });
+    };
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (stdoutOverflow) return;
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > request.maxStdoutBytes) {
+        stdoutOverflow = true;
+        terminate();
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (stderrBytes >= request.maxStderrBytes) return;
+      const room = request.maxStderrBytes - stderrBytes;
+      const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
+      stderrBytes += kept.length;
+      stderr.push(kept);
+    });
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      finish({ exitCode: null, signal: null, spawnError: error.code ?? "spawn_failed" });
+    });
+    child.on("close", (exitCode, signal) => {
+      finish({ exitCode, signal, spawnError: null });
+    });
+    // A CLI that exits before reading stdin raises EPIPE; the exit status still decides.
+    child.stdin.on("error", () => {});
+    child.stdin.end(request.stdin ?? "");
+  });

package/src/schema.ts

@@ -0,0 +1,164 @@
+import { z } from "zod";
+
+/**
+ * JSON shapes printed by pass-cli 2.4.2 with `--output json` (serde of the
+ * pass crate and proton-pass-common 2.1.1 types). Unknown keys are dropped;
+ * only what the adapter maps is validated, so additive upstream fields do not
+ * break parsing while a changed shape fails closed.
+ */
+
+const Id = z.string().min(1).max(512);
+/** jiff civil date-time; pass-cli runs with TZ=UTC so it is UTC wall time. */
+const CivilDateTime = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?$/);
+
+const ShareRole = z.union([
+  z.enum(["Owner", "Manager", "Editor", "Viewer"]),
+  z.object({
+    Custom: z.object({ name: z.string().optional(), permission: z.number().int().min(0) }),
+  }),
+]);
+export type ShareRole = z.infer<typeof ShareRole>;
+
+/** `share list --only-vaults=true --output json` */
+export const ShareListOutput = z.object({
+  shares: z.array(
+    z.object({
+      id: Id,
+      name: z.string(),
+      share_type: z.string(),
+      share_role: ShareRole,
+    }),
+  ),
+});
+export type ShareListOutput = z.infer<typeof ShareListOutput>;
+
+/** `vault list --output json` (fallback when share roles are unavailable). */
+export const VaultListOutput = z.object({
+  vaults: z.array(z.object({ name: z.string(), vault_id: Id, share_id: Id })),
+});
+
+export const ExtraFieldContent = z.union([
+  z.object({ Text: z.string() }),
+  z.object({ Hidden: z.string() }),
+  z.object({ Totp: z.string() }),
+  z.object({ Timestamp: z.number().int() }),
+]);
+export const ExtraField = z.object({ name: z.string(), content: ExtraFieldContent });
+export type ExtraField = z.infer<typeof ExtraField>;
+
+const Section = z.object({ section_name: z.string(), section_fields: z.array(ExtraField) });
+export type Section = z.infer<typeof Section>;
+
+const OptionalString = z
+  .string()
+  .nullish()
+  .transform((value) => value ?? "");
+
+const LoginContent = z.object({
+  email: OptionalString,
+  username: OptionalString,
+  password: OptionalString,
+  urls: z.array(z.string()).default([]),
+  totp_uri: OptionalString,
+});
+const SshKeyContent = z.object({
+  private_key: OptionalString,
+  public_key: OptionalString,
+  sections: z.array(Section).default([]),
+});
+const WifiContent = z.object({
+  ssid: OptionalString,
+  password: OptionalString,
+  sections: z.array(Section).default([]),
+});
+const CreditCardContent = z.object({
+  cardholder_name: OptionalString,
+  number: OptionalString,
+  verification_number: OptionalString,
+  expiration_date: OptionalString,
+  pin: OptionalString,
+});
+/** Identity carries many scalar strings plus extra field groups; kept loose. */
+const IdentityContent = z.record(z.string(), z.unknown());
+const CustomContent = z.object({ sections: z.array(Section).default([]) });
+
+export const ItemContentVariant = z.union([
+  z.object({ Note: z.null() }).strict(),
+  z.object({ Alias: z.null() }).strict(),
+  z.object({ Login: LoginContent }),
+  z.object({ SshKey: SshKeyContent }),
+  z.object({ Wifi: WifiContent }),
+  z.object({ CreditCard: CreditCardContent }),
+  z.object({ Identity: IdentityContent }),
+  z.object({ Custom: CustomContent }),
+  z.literal("Note"),
+  z.literal("Alias"),
+]);
+export type ItemContentVariant = z.infer<typeof ItemContentVariant>;
+
+export const Item = z.object({
+  id: Id,
+  share_id: Id,
+  vault_id: z.string().optional(),
+  content: z.object({
+    title: z.string(),
+    note: OptionalString,
+    content: ItemContentVariant,
+    extra_fields: z.array(ExtraField).default([]),
+  }),
+  state: z.string(),
+  flags: z.array(z.string()).default([]),
+  create_time: CivilDateTime,
+  modify_time: CivilDateTime,
+});
+export type Item = z.infer<typeof Item>;
+
+export const Attachment = z.object({
+  id: Id,
+  size: z.number().int().min(0),
+  content: z.object({ name: z.string(), mime_type: z.string().optional() }),
+});
+export type Attachment = z.infer<typeof Attachment>;
+
+/** `item view --output json`: `ItemDetails`. */
+export const ItemDetails = z.object({
+  item: Item,
+  attachments: z.array(Attachment).default([]),
+});
+export type ItemDetails = z.infer<typeof ItemDetails>;
+
+/** `item list --show-secrets --output json` (non-agent sessions only). */
+export const FullItemList = z.object({ items: z.array(Item) });
+
+/** `item list --output json`: secret-free summaries (the only form agent sessions get). */
+export const ItemSummary = z.object({
+  id: Id,
+  share_id: Id,
+  state: z.string(),
+  flags: z.array(z.string()).default([]),
+  create_time: CivilDateTime,
+  modify_time: CivilDateTime,
+  title: z.string(),
+  item_type: z.string(),
+});
+export type ItemSummary = z.infer<typeof ItemSummary>;
+export const ItemSummaryList = z.object({ items: z.array(ItemSummary) });
+
+/** `info --output json` for a personal-access-token or agent session. */
+export const InfoOutput = z.object({
+  personal_access_token_name: z.string().optional(),
+  username: z.string().optional(),
+  session_has_lock: z.boolean().optional(),
+});
+
+export const ITEM_HAS_FILES = "ItemHasFiles";
+
+/** Proton share permission flags (proton-pass-common ShareRole::Custom). */
+export const SHARE_PERMISSION = {
+  admin: 1,
+  read: 2,
+  create: 4,
+  update: 8,
+  trash: 16,
+  delete: 32,
+} as const;