@opengeni/vaults-protonpass 0.0.0-stage → 3.3.0

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@opengeni/vaults-protonpass",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.3.0",
+  "description": "Proton Pass provider for Opengeni vaults over an operator-installed, version-pinned pass-cli and a scoped personal access token. Load it only through dynamic import() from the API and worker.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cloudgeni-ai/opengeni.git",
+    "directory": "packages/vaults-protonpass"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun ../../scripts/build-typescript-package.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bash ../../scripts/prepublish-guard"
+  },
+  "dependencies": {
+    "@opengeni/contracts": "3.3.0",
+    "@opengeni/vaults": "3.3.0",
+    "zod": "^4.2.1"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/contract.ts

@@ -0,0 +1,29 @@
+/**
+ * The shared vault contracts this adapter implements, re-exported for the
+ * package's modules so every file names one source.
+ */
+export {
+  VaultProviderError,
+  type ProviderCallBudget,
+  type ProviderCallOperation,
+  type ProviderFieldMeta,
+  type ProviderFieldValue,
+  type ProviderItemMeta,
+  type ProviderVault,
+  type ProviderWriteField,
+  type ProviderWriteItem,
+  type VaultProvider,
+  type VaultProviderAuthority,
+  type VaultProviderCapabilities,
+  type VaultProviderContext,
+  type VaultProviderErrorCode,
+} from "@opengeni/vaults";
+export {
+  VAULT_LIMITS,
+  parseTotpInput,
+  type SecretMaterial,
+  type TotpParams,
+  type VaultFieldKind,
+  type VaultItemType,
+  type VaultProviderOperations,
+} from "@opengeni/contracts";

package/src/errors.ts

@@ -0,0 +1,287 @@
+import { VaultProviderError } from "./contract";
+import type { ProcessResult } from "./runner";
+
+/**
+ * pass-cli 2.4.2 prints anyhow errors as `Error: <context>\n\nCaused by:\n …`.
+ * API failures surface as `Could not perform operation. Reason: <ProtonApiErrorCode>`
+ * (pass/src/macros.rs `assert_response!`) or `Invalid status code: <status>`.
+ * The reason form appears whenever a non-2xx body carries a `Code` that
+ * pass/src/error.rs `ProtonApiErrorCode` knows, whatever the HTTP status, so
+ * a reason alone does not prove a 4xx; the status form appears otherwise.
+ * stderr is never returned to callers; only the classification below is.
+ */
+const REASON = /Could not perform operation\. Reason: ([A-Za-z]+)/;
+const STATUS = /Invalid status code(?: for download chunk)?: (\d{3})/;
+
+/** The session can no longer be used; a fresh login is required. */
+export const SESSION_INVALIDATED = /Your session has been invalidated/;
+/** Pre-flight: the CLI found no usable session before contacting the API. */
+export const NOT_AUTHENTICATED = /This operation requires an authenticated client/;
+
+const NOT_FOUND =
+  /Item not found|Share with id \S+ not found|Could not find vault|Could not find item|Attachment not found/;
+const NETWORK =
+  /error sending request|dns error|failed to lookup address|Connection refused|connection (?:reset|closed)|operation timed out|tcp connect error|certificate/i;
+
+const PERMISSION_REASONS = new Set([
+  "PermissionDenied",
+  "NotAllowed",
+  "InsufficientScope",
+  "AdminPermissionMissing",
+  "Banned",
+  "FeatureDisabled",
+]);
+const NOT_FOUND_REASONS = new Set(["NotExists", "DeletedShare"]);
+const CONFLICT_REASONS = new Set(["NotLatestRevision", "NotLatestKey", "AlreadyExists"]);
+const QUOTA_REASONS = new Set(["NoQuotaLeft", "ResourceLimitExceeded", "PayloadTooLarge"]);
+
+/** The Proton API error code name in stderr, if any (a closed enum, safe to report). */
+export function protonReason(stderr: string): string | null {
+  return REASON.exec(stderr)?.[1] ?? null;
+}
+
+export function protonStatus(stderr: string): number | null {
+  const match = STATUS.exec(stderr);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Statuses with which Proton refuses a request before applying it: a bad or
+ * invalid request (400, 422), an unauthorised or forbidden one (401, 403), a
+ * missing target (404), a conflict (409), an oversized payload (413) or
+ * throttling (429). Any other status (500, 502, 503, 504 from Proton or a
+ * proxy, or anything unexpected) may follow an applied change.
+ */
+export const PROTON_DEFINITE_REJECTION_STATUSES: ReadonlySet<number> = new Set([
+  400, 401, 403, 404, 409, 413, 422, 429,
+]);
+
+/**
+ * `ProtonApiErrorCode` names (pass-cli 2.4.2 pass/src/error.rs) that describe
+ * a refusal of the request itself: permission, a missing or deleted target, a
+ * stale revision or key, a lock, a quota, or invalid input. Server-side
+ * failures that may follow a partial write (`Timeout`, `InsertFailed`,
+ * `SelectFailed`, `UploadFailure`, the `Provider*` family) and any name not
+ * listed here leave a mutation's outcome unknown.
+ */
+export const PROTON_DEFINITE_REJECTION_REASONS: ReadonlySet<string> = new Set([
+  ...PERMISSION_REASONS,
+  ...NOT_FOUND_REASONS,
+  ...CONFLICT_REASONS,
+  ...QUOTA_REASONS,
+  "SessionLocked",
+  "IsLocked",
+  "InvalidSignature",
+  "MissingKeys",
+  "RotationPayloadIncomplete",
+  "IncompatibleState",
+  "BadLockId",
+  "InvalidRequirements",
+  "InvalidValue",
+  "InvalidType",
+  "ValueOutOfBounds",
+  "NotNull",
+  "NotEmpty",
+  "NotTrue",
+  "NotFalse",
+  "NotEqual",
+  "Equal",
+  "NotSameAsField",
+  "RegexError",
+  "InvalidNumber",
+  "InvalidLength",
+  "TooShort",
+  "TooLong",
+  "HashNotEqual",
+  "EmailFormat",
+  "IpFormat",
+  "UrlFormat",
+  "CurrencyFormat",
+  "LocaleFormat",
+  "DateFormat",
+  "JsonFormat",
+  "MimeFormat",
+  "PhoneFormat",
+  "DomainFormat",
+  "PgpFormat",
+  "IdFormat",
+  "HexFormat",
+  "Base64Format",
+  "VersionFormat",
+  "ImageFormat",
+]);
+
+/**
+ * True when stderr shows Proton refused the request without applying it: a
+ * known rejection reason, or (when no reason was decoded) a rejection status.
+ */
+export function isDefiniteRejection(stderr: string): boolean {
+  const reason = protonReason(stderr);
+  if (reason !== null) return PROTON_DEFINITE_REJECTION_REASONS.has(reason);
+  const status = protonStatus(stderr);
+  return status !== null && PROTON_DEFINITE_REJECTION_STATUSES.has(status);
+}
+
+/**
+ * Maps a failed pass-cli run to a provider error. `subject` names the action in
+ * the message (for example "list items"); stderr content never leaves here
+ * except the closed Proton error-code name.
+ */
+export function mapProtonFailure(result: ProcessResult, subject: string): VaultProviderError {
+  if (result.spawnError) {
+    return new VaultProviderError("provider_unavailable", "pass-cli could not be started");
+  }
+  if (result.timedOut) {
+    return new VaultProviderError("provider_unavailable", `Proton Pass timed out (${subject})`);
+  }
+  if (result.aborted) {
+    return new VaultProviderError(
+      "provider_unavailable",
+      `Proton Pass call cancelled (${subject})`,
+    );
+  }
+  const stderr = result.stderr;
+  if (SESSION_INVALIDATED.test(stderr) || NOT_AUTHENTICATED.test(stderr)) {
+    return new VaultProviderError(
+      "provider_auth_expired",
+      "The Proton Pass session ended; sign in again with the personal access token",
+    );
+  }
+  const reason = protonReason(stderr);
+  if (reason) {
+    if (reason === "SessionLocked" || reason === "IsLocked") {
+      return new VaultProviderError("provider_locked", "The Proton Pass session is locked");
+    }
+    if (PERMISSION_REASONS.has(reason)) {
+      return new VaultProviderError(
+        "provider_permission_denied",
+        `The Proton Pass token may not ${subject} (${reason})`,
+      );
+    }
+    if (NOT_FOUND_REASONS.has(reason)) {
+      return new VaultProviderError("provider_not_found", "No such Proton Pass vault or item");
+    }
+    if (CONFLICT_REASONS.has(reason)) {
+      return new VaultProviderError(
+        "provider_conflict",
+        `Proton Pass rejected the change because the item changed (${reason})`,
+      );
+    }
+    if (QUOTA_REASONS.has(reason)) {
+      return new VaultProviderError(
+        "provider_unavailable",
+        `Proton Pass refused the request: account limit reached (${reason})`,
+      );
+    }
+    return new VaultProviderError(
+      "provider_unavailable",
+      `Proton Pass rejected the request (${reason})`,
+    );
+  }
+  const status = protonStatus(stderr);
+  if (status !== null) {
+    if (status === 429) {
+      return new VaultProviderError(
+        "provider_rate_limited",
+        "Proton Pass is rate limiting",
+        60_000,
+      );
+    }
+    if (status === 401) {
+      return new VaultProviderError("provider_auth_expired", "The Proton Pass session expired");
+    }
+    if (status === 403) {
+      return new VaultProviderError(
+        "provider_permission_denied",
+        `The Proton Pass token may not ${subject}`,
+      );
+    }
+    if (status === 404) {
+      return new VaultProviderError("provider_not_found", "No such Proton Pass vault or item");
+    }
+    if (status === 409) {
+      return new VaultProviderError("provider_conflict", "Proton Pass reported a conflict");
+    }
+    return new VaultProviderError("provider_unavailable", `Proton Pass returned HTTP ${status}`);
+  }
+  if (NOT_FOUND.test(stderr)) {
+    return new VaultProviderError("provider_not_found", "No such Proton Pass vault or item");
+  }
+  if (NETWORK.test(stderr)) {
+    return new VaultProviderError("provider_unavailable", "Proton Pass could not be reached");
+  }
+  return new VaultProviderError("provider_unavailable", `Proton Pass could not ${subject}`);
+}
+
+/**
+ * Markers proving a mutation failed before anything was sent: bad input, no
+ * session, or the agent-reason check (`ensure_reason_if_agent`) that runs first.
+ */
+const PRE_FLIGHT =
+  /Error parsing JSON|Error parsing template JSON|Error reading (?:from stdin|template)|Error converting template|requires an authenticated client|Agent sessions must set the PROTON_PASS_AGENT_REASON|PROTON_PASS_AGENT_REASON is (?:set but empty|too long)|Invalid field type|Invalid timestamp value|Please provide either|Error creating trash item request|Could not find vault|Share with id \S+ not found/;
+
+/**
+ * Whether a failed mutation is known not to have taken effect. Only a server
+ * rejection inside the mutation's own error context (`Error creating …`,
+ * `Error trashing item`) with a known rejection reason or status, or a
+ * pre-flight marker, counts. A server error (500, 502, 503, 504 or any other
+ * status or reason outside the rejection sets), a timeout, a signal, a
+ * cancelled call or an error after the request (for example the agent monitor
+ * event sent after a create) leaves the outcome unknown.
+ */
+export function isDefiniteMutationFailure(result: ProcessResult, mutationContext: RegExp): boolean {
+  if (result.spawnError) return true;
+  if (result.timedOut || result.aborted || result.signal !== null || result.stdoutOverflow) {
+    return false;
+  }
+  if (result.exitCode === null) return false;
+  const stderr = result.stderr;
+  if (SESSION_INVALIDATED.test(stderr)) return false;
+  if (PRE_FLIGHT.test(stderr)) return true;
+  return mutationContext.test(stderr) && isDefiniteRejection(stderr);
+}
+
+export function outcomeUnknown(subject: string): VaultProviderError {
+  return new VaultProviderError(
+    "provider_outcome_unknown",
+    `Proton Pass may or may not have completed "${subject}"; check the vault before retrying`,
+  );
+}
+
+/** pass-cli's context for a token login the API answered (`Error logging in with personal access token`). */
+const LOGIN_CONTEXT = /Error logging in with personal access token/;
+/** Statuses with which Proton's API refuses the token itself. */
+const LOGIN_REJECTED_STATUSES = new Set([400, 401, 403, 422]);
+
+/**
+ * Maps a failed `pass-cli login`. Only Proton's own refusal of the token
+ * (a 400, 401, 403 or 422 answer, or a permission or not-found reason, in
+ * the token-login context) asks the customer for a new token. Local
+ * failures (key provider, disk, an unexpected CLI error), network trouble,
+ * throttling and server errors are `provider_unavailable` or
+ * `provider_rate_limited`; reconnecting would not help with them.
+ */
+export function loginFailure(result: ProcessResult): VaultProviderError {
+  const stderr = result.stderr;
+  const answered =
+    !result.spawnError && !result.timedOut && !result.aborted && LOGIN_CONTEXT.test(stderr);
+  if (answered) {
+    const status = protonStatus(stderr);
+    const reason = protonReason(stderr);
+    if (
+      (status !== null && LOGIN_REJECTED_STATUSES.has(status)) ||
+      (reason !== null && (PERMISSION_REASONS.has(reason) || NOT_FOUND_REASONS.has(reason)))
+    ) {
+      return new VaultProviderError(
+        "provider_auth_invalid",
+        "Proton Pass rejected the personal access token (revoked, expired or mistyped)",
+      );
+    }
+  }
+  const mapped = mapProtonFailure(result, "sign in");
+  // Outside the API's verdict on the token, no other mapping (expired
+  // session, permission, not found) describes a failed login accurately.
+  if (mapped.code === "provider_rate_limited") return mapped;
+  if (mapped.code === "provider_unavailable") return mapped;
+  return new VaultProviderError("provider_unavailable", "Proton Pass could not sign in");
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export {
+  PROTON_PASS_MAX_ITEM_VIEWS_PER_LIST,
+  PROTON_PASS_OPERATIONS,
+  PROTON_PASS_VALUE_CACHE_MS,
+  createProtonPassVaultProvider,
+  protonPassCapabilities,
+  type ProtonPassVaultProvider,
+  type ProtonPassVaultProviderOptions,
+} from "./provider";
+export {
+  PROTON_PASS_CLI_VERSION,
+  PROTON_PASS_COMMAND_TIMEOUT_MS,
+  PROTON_PASS_IDLE_CLOSE_MS,
+  PROTON_PASS_MAX_PROCESSES,
+  PROTON_PASS_SESSION_MAX_AGE_MS,
+  type ProtonCliOptions,
+} from "./session";
+export { FILE_FIELD_PREFIX, LOGIN_FIELD_IDS, NOTE_FIELD_ID } from "./mapping";
+export {
+  PROTON_PASS_POOL_BUSY_RETRY_MS,
+  PROTON_PASS_POOL_IDLE_MS,
+  PROTON_PASS_POOL_MAX_SESSIONS,
+  createProtonPassProviderPool,
+  type ProtonPassPoolProviderOptions,
+  type ProtonPassProviderPool,
+  type ProtonPassProviderPoolOptions,
+} from "./pool";
+export { restrictToOperations } from "./operations";
+export type { ProcessRequest, ProcessResult, ProcessRunner } from "./runner";

package/src/mapping.ts

@@ -0,0 +1,247 @@
+import {
+  type ProviderFieldMeta,
+  type ProviderItemMeta,
+  type VaultFieldKind,
+  type VaultItemType,
+} from "./contract";
+import { safeFieldName, safeSecretName, uniqueName } from "./naming";
+import type { Attachment, ExtraField, Item, ItemContentVariant, Section } from "./schema";
+
+/**
+ * External field ids. They are positional names, not upstream ids: Proton
+ * items have no per-field identifiers, so ids are derived from the field's
+ * place in the item (`login.password`, `x:<extra field name>`,
+ * `s:<section>/<field>`, `@file:<attachment id>`), with `#n` for repeats.
+ */
+export const NOTE_FIELD_ID = "@note";
+export const FILE_FIELD_PREFIX = "@file:";
+export const LOGIN_FIELD_IDS = {
+  username: "login.username",
+  email: "login.email",
+  password: "login.password",
+  totp: "login.totp",
+} as const;
+export const TOTP_FIELD_NAME = "one-time password";
+
+export type MappedValue =
+  | { type: "text"; value: string }
+  | { type: "totp"; uri: string }
+  | { type: "file"; attachment: Attachment };
+
+export interface MappedField extends ProviderFieldMeta {
+  value: MappedValue;
+}
+
+export interface MappedItem {
+  meta: ProviderItemMeta;
+  fields: MappedField[];
+}
+
+const IDENTITY_CONCEALED = new Set(["social_security_number", "passport_number", "license_number"]);
+
+class FieldCollector {
+  readonly fields: MappedField[] = [];
+  private readonly names = new Set<string>();
+  private readonly ids = new Map<string, number>();
+
+  add(baseId: string, rawName: string, kind: VaultFieldKind, value: MappedValue) {
+    const seen = (this.ids.get(baseId) ?? 0) + 1;
+    this.ids.set(baseId, seen);
+    const externalFieldId = seen === 1 ? baseId : `${baseId}#${seen}`;
+    const name = uniqueName(safeFieldName(rawName, "field"), this.names);
+    this.fields.push({ externalFieldId, name, kind, value });
+  }
+
+  extra(prefix: string, field: ExtraField) {
+    const content = field.content;
+    const id = `${prefix}${field.name}`;
+    if ("Text" in content) this.add(id, field.name, "text", { type: "text", value: content.Text });
+    else if ("Hidden" in content) {
+      this.add(id, field.name, "concealed", { type: "text", value: content.Hidden });
+    } else if ("Totp" in content) {
+      // An empty TOTP field holds no seed; it reads as empty text.
+      if (content.Totp) this.add(id, field.name, "totp", { type: "totp", uri: content.Totp });
+      else this.add(id, field.name, "text", { type: "text", value: "" });
+    } else {
+      this.add(id, field.name, "text", { type: "text", value: timestampText(content.Timestamp) });
+    }
+  }
+
+  sections(sections: readonly Section[]) {
+    for (const section of sections) {
+      for (const field of section.section_fields) this.extra(`s:${section.section_name}/`, field);
+    }
+  }
+}
+
+function timestampText(seconds: number): string {
+  const date = new Date(seconds * 1000);
+  return Number.isNaN(date.getTime()) ? String(seconds) : date.toISOString();
+}
+
+function variantName(content: ItemContentVariant): string {
+  if (typeof content === "string") return content;
+  return Object.keys(content)[0] ?? "Note";
+}
+
+export function itemTypeForVariant(variant: string): VaultItemType {
+  switch (variant) {
+    case "Login":
+      return "login";
+    case "Note":
+      return "note";
+    case "Custom":
+    case "SshKey":
+      return "api_key";
+    default:
+      // Alias, CreditCard, Identity, Wifi: generic fields, shown as notes.
+      return "note";
+  }
+}
+
+/** Proton summary `item_type` (snake case) to an Opengeni item type. */
+export function itemTypeForSummary(itemType: string): VaultItemType {
+  switch (itemType) {
+    case "login":
+      return "login";
+    case "custom":
+    case "ssh_key":
+      return "api_key";
+    default:
+      return "note";
+  }
+}
+
+/** `YYYY-MM-DDTHH:MM:SS` (UTC under TZ=UTC) to an ISO instant. */
+export function civilToIso(civil: string): string | null {
+  const date = new Date(`${civil}Z`);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function concealedText(collector: FieldCollector, id: string, name: string, value: string) {
+  collector.add(id, name, "concealed", { type: "text", value });
+}
+
+function plainText(collector: FieldCollector, id: string, name: string, value: string) {
+  collector.add(id, name, "text", { type: "text", value });
+}
+
+function identityFields(collector: FieldCollector, identity: Record<string, unknown>) {
+  for (const [key, value] of Object.entries(identity)) {
+    if (typeof value === "string") {
+      if (!value) continue;
+      if (IDENTITY_CONCEALED.has(key)) concealedText(collector, `identity.${key}`, key, value);
+      else plainText(collector, `identity.${key}`, key, value);
+      continue;
+    }
+    if (!Array.isArray(value)) continue;
+    for (const entry of value) {
+      if (!entry || typeof entry !== "object") continue;
+      const record = entry as Record<string, unknown>;
+      if (typeof record.section_name === "string" && Array.isArray(record.section_fields)) {
+        collector.sections([
+          { section_name: record.section_name, section_fields: extraFields(record.section_fields) },
+        ]);
+      } else {
+        for (const field of extraFields([record])) collector.extra(`s:${key}/`, field);
+      }
+    }
+  }
+}
+
+function extraFields(values: readonly unknown[]): ExtraField[] {
+  const out: ExtraField[] = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object") continue;
+    const record = value as { name?: unknown; content?: unknown };
+    if (typeof record.name !== "string" || !record.content || typeof record.content !== "object") {
+      continue;
+    }
+    const content = record.content as Record<string, unknown>;
+    if (typeof content.Text === "string")
+      out.push({ name: record.name, content: { Text: content.Text } });
+    else if (typeof content.Hidden === "string") {
+      out.push({ name: record.name, content: { Hidden: content.Hidden } });
+    } else if (typeof content.Totp === "string") {
+      out.push({ name: record.name, content: { Totp: content.Totp } });
+    } else if (typeof content.Timestamp === "number") {
+      out.push({ name: record.name, content: { Timestamp: content.Timestamp } });
+    }
+  }
+  return out;
+}
+
+/** Maps an item (and, from `item view`, its attachments) to fields and metadata. */
+export function mapItem(item: Item, attachments: readonly Attachment[] = []): MappedItem {
+  const collector = new FieldCollector();
+  const content = item.content.content;
+  const variant = variantName(content);
+  const websites: string[] = [];
+
+  if (typeof content === "object") {
+    if ("Login" in content) {
+      const login = content.Login;
+      plainText(collector, LOGIN_FIELD_IDS.username, "username", login.username);
+      if (login.email) plainText(collector, LOGIN_FIELD_IDS.email, "email", login.email);
+      concealedText(collector, LOGIN_FIELD_IDS.password, "password", login.password);
+      if (login.totp_uri) {
+        collector.add(LOGIN_FIELD_IDS.totp, TOTP_FIELD_NAME, "totp", {
+          type: "totp",
+          uri: login.totp_uri,
+        });
+      }
+      websites.push(...login.urls.filter((url) => url.trim().length > 0));
+    } else if ("SshKey" in content) {
+      concealedText(collector, "ssh.private_key", "private key", content.SshKey.private_key);
+      plainText(collector, "ssh.public_key", "public key", content.SshKey.public_key);
+      collector.sections(content.SshKey.sections);
+    } else if ("Wifi" in content) {
+      plainText(collector, "wifi.ssid", "ssid", content.Wifi.ssid);
+      concealedText(collector, "wifi.password", "password", content.Wifi.password);
+      collector.sections(content.Wifi.sections);
+    } else if ("CreditCard" in content) {
+      const card = content.CreditCard;
+      plainText(collector, "card.cardholder_name", "cardholder name", card.cardholder_name);
+      concealedText(collector, "card.number", "number", card.number);
+      concealedText(
+        collector,
+        "card.verification_number",
+        "verification number",
+        card.verification_number,
+      );
+      plainText(collector, "card.expiration_date", "expiration date", card.expiration_date);
+      if (card.pin) concealedText(collector, "card.pin", "PIN", card.pin);
+    } else if ("Identity" in content) {
+      identityFields(collector, content.Identity);
+    } else if ("Custom" in content) {
+      collector.sections(content.Custom.sections);
+    }
+  }
+
+  const note = item.content.note;
+  if (variant === "Note" || note) {
+    collector.add(NOTE_FIELD_ID, "note", "concealed", { type: "text", value: note });
+  }
+  for (const field of item.content.extra_fields) collector.extra("x:", field);
+  for (const attachment of attachments) {
+    collector.add(`${FILE_FIELD_PREFIX}${attachment.id}`, attachment.content.name, "file", {
+      type: "file",
+      attachment,
+    });
+  }
+
+  const meta: ProviderItemMeta = {
+    externalItemId: item.id,
+    name: safeSecretName(item.content.title, item.id),
+    type: itemTypeForVariant(variant),
+    websites,
+    fields: collector.fields.map(({ externalFieldId, name, kind }) => ({
+      externalFieldId,
+      name,
+      kind,
+    })),
+    version: item.modify_time,
+    updatedAt: civilToIso(item.modify_time),
+  };
+  return { meta, fields: collector.fields };
+}

package/src/naming.ts

@@ -0,0 +1,44 @@
+import { type TotpParams, VAULT_LIMITS } from "./contract";
+
+// Mirrors contracts isValidSecretName (Q-10): no / { } # \ or control chars,
+// trimmed, 1..120 chars, not "id:…"; field names additionally may not be "otp".
+const FORBIDDEN_NAME_CHARS = /[/{}#\\\u0000-\u001f\u007f-\u009f]/g;
+
+export function nameKey(name: string): string {
+  return name.normalize("NFC").trim().toLowerCase();
+}
+
+export function safeSecretName(raw: string, fallback: string): string {
+  const max = VAULT_LIMITS.nameMaxChars;
+  let name = raw.replace(FORBIDDEN_NAME_CHARS, "-").trim().slice(0, max).trim();
+  if (!name) name = fallback.replace(FORBIDDEN_NAME_CHARS, "-").trim().slice(0, max) || "item";
+  if (/^id:/i.test(name)) name = `id-${name.slice(3)}`;
+  return name;
+}
+
+export function safeFieldName(raw: string, fallback: string): string {
+  const name = safeSecretName(raw, fallback);
+  return nameKey(name) === "otp" ? "otp-code" : name;
+}
+
+/** Appends " (2)", " (3)" … so names are unique case-insensitively. */
+export function uniqueName(name: string, taken: Set<string>): string {
+  let candidate = name;
+  for (let n = 2; taken.has(nameKey(candidate)); n += 1) {
+    const suffix = ` (${n})`;
+    candidate = `${name.slice(0, VAULT_LIMITS.nameMaxChars - suffix.length)}${suffix}`;
+  }
+  taken.add(nameKey(candidate));
+  return candidate;
+}
+
+/** A canonical otpauth URI for a parsed seed, for stores that require URIs. */
+export function totpUri(params: TotpParams, label: string): string {
+  const query = new URLSearchParams({
+    secret: params.secretBase32,
+    algorithm: params.algorithm,
+    digits: String(params.digits),
+    period: String(params.periodSeconds),
+  });
+  return `otpauth://totp/${encodeURIComponent(label || "Opengeni")}?${query.toString()}`;
+}