@opengeni/api-router 3.0.1 → 3.1.2

package/src/interaction-secrets-vault.ts

@@ -0,0 +1,213 @@
+/**
+ * The vault-backed `InteractionSecretsPort` (design §10B.4, Q-32, D20): the
+ * real secret resolver for agent Browser and Computer actions, and passkey
+ * items for the session's virtual authenticators.
+ */
+import type { VaultProviderRegistry } from "@opengeni/vaults";
+import {
+  type BrowserPasskeyCredential,
+  type BrowserPasskeyCredentialMaterial,
+  PASSKEY_FIELD_NAMES,
+  type SecretPrincipal,
+  type SecretResolver,
+} from "@opengeni/contracts";
+import { createSecretResolver, createVaultService, type VaultService } from "@opengeni/core";
+import {
+  type Database,
+  decryptEnvironmentValue,
+  getSession,
+  getVaultItem,
+  isVaultError,
+  leaseVaultPasskeys,
+  readVaultFieldCiphertext,
+  releaseVaultPasskeyLeases,
+  updatePasskeySignCount,
+  type VaultItemRow,
+} from "@opengeni/db";
+import type {
+  AttemptSecretPrincipal,
+  InteractionPasskeyStore,
+  InteractionSecretsPort,
+} from "./interaction-secrets";
+
+const CAPABILITY_CACHE_MS = 30_000;
+const CAPABILITY_CACHE_LIMIT = 512;
+const HOLDER_PRINCIPALS_LIMIT = 1_024;
+
+type PasskeyFieldName = (typeof PASSKEY_FIELD_NAMES)[number];
+
+function fieldKey(name: string): string {
+  return name.toLowerCase();
+}
+
+/** `/`, `{`, `}`, `#` and `\` are not allowed in vault names. */
+function safeName(value: string): string {
+  return value.replace(/[/{}#\\\p{Cc}]/gu, "-").trim();
+}
+
+export function passkeyItemName(credential: BrowserPasskeyCredentialMaterial): string {
+  const user = credential.userName?.trim() || credential.userDisplayName?.trim() || null;
+  return safeName(
+    user ? `${credential.rpId} passkey for ${user}` : `${credential.rpId} passkey`,
+  ).slice(0, 180);
+}
+
+export function createVaultInteractionSecretsPort(deps: {
+  db: Database;
+  /** The variable-set envelope key; null fails value reads like the vault API. */
+  encryptionKey: Uint8Array | null;
+  /** Defaults to a service over the same database and key. */
+  vaultService?: VaultService;
+  /** Connected vaults (1Password, host) for a workspace's acting subject. */
+  providersFor?: (workspaceId: string, subjectId: string | null) => VaultProviderRegistry;
+}): InteractionSecretsPort {
+  const encryptionKey = deps.encryptionKey;
+  let service = deps.vaultService ?? null;
+  const vaults = (): VaultService =>
+    (service ??= createVaultService({ db: deps.db, encryptionKey }));
+  const capabilities = new Map<string, { enabled: boolean; at: number }>();
+  /** Lease holders to the principal that leased, so a release can be scoped. */
+  const holders = new Map<string, AttemptSecretPrincipal>();
+
+  async function secretsEnabled(principal: AttemptSecretPrincipal): Promise<boolean> {
+    const cached = capabilities.get(principal.sessionId);
+    if (cached && Date.now() - cached.at < CAPABILITY_CACHE_MS) return cached.enabled;
+    const session = await getSession(deps.db, principal.workspaceId, principal.sessionId);
+    const enabled = session?.agent?.capabilities.secrets ?? true;
+    capabilities.delete(principal.sessionId);
+    capabilities.set(principal.sessionId, { enabled, at: Date.now() });
+    while (capabilities.size > CAPABILITY_CACHE_LIMIT) {
+      capabilities.delete(capabilities.keys().next().value!);
+    }
+    return enabled;
+  }
+
+  function context(principal: SecretPrincipal) {
+    return { kind: "principal" as const, principal };
+  }
+
+  function requireKey(): Uint8Array {
+    if (!encryptionKey) throw new Error("vault encryption key is not configured");
+    return encryptionKey;
+  }
+
+  async function credentialFromItem(
+    principal: AttemptSecretPrincipal,
+    row: VaultItemRow,
+  ): Promise<BrowserPasskeyCredential | null> {
+    const values = new Map<PasskeyFieldName, string>();
+    for (const name of PASSKEY_FIELD_NAMES) {
+      const field = row.fields.find((candidate) => fieldKey(candidate.name) === fieldKey(name));
+      if (!field) continue;
+      let stored = field.valueEncrypted ?? null;
+      if (stored === null) {
+        stored = (
+          await readVaultFieldCiphertext(deps.db, context(principal), {
+            fieldId: field.id,
+            purpose: "internal",
+            metadata: { surface: "browser", use: "passkey_load" },
+          })
+        ).valueEncrypted;
+      }
+      if (stored !== null) values.set(name, decryptEnvironmentValue(requireKey(), stored));
+    }
+    const rpId = values.get("rpId");
+    const credentialId = values.get("credentialId");
+    const privateKey = values.get("privateKey");
+    if (!rpId || !credentialId || !privateKey) return null;
+    return {
+      itemId: row.id,
+      rpId,
+      credentialId,
+      userHandle: values.get("userHandle") || null,
+      userName: values.get("userName") || null,
+      userDisplayName: null,
+      privateKey,
+      signCount: Math.max(0, Math.min(0xffff_ffff, Number(row.passkeySignCount ?? 0))),
+    };
+  }
+
+  const passkeys: InteractionPasskeyStore = {
+    async lease(principal, holder, ttlSeconds) {
+      holders.delete(holder);
+      holders.set(holder, principal);
+      while (holders.size > HOLDER_PRINCIPALS_LIMIT) holders.delete(holders.keys().next().value!);
+      const itemIds = await leaseVaultPasskeys(deps.db, context(principal), {
+        holder,
+        ttlSeconds,
+      });
+      const credentials: BrowserPasskeyCredential[] = [];
+      for (const itemId of itemIds) {
+        const row = await getVaultItem(deps.db, context(principal), { itemId });
+        const credential = await credentialFromItem(principal, row);
+        if (credential) credentials.push(credential);
+      }
+      return credentials;
+    },
+    async saveRegistered(principal, { credential, origin }) {
+      const fields = [
+        { name: "rpId", kind: "text" as const, value: credential.rpId },
+        { name: "credentialId", kind: "text" as const, value: credential.credentialId },
+        ...(credential.userHandle
+          ? [{ name: "userHandle", kind: "text" as const, value: credential.userHandle }]
+          : []),
+        ...(credential.userName
+          ? [{ name: "userName", kind: "text" as const, value: credential.userName }]
+          : []),
+        { name: "privateKey", kind: "concealed" as const, value: credential.privateKey },
+      ];
+      const base = passkeyItemName(credential);
+      let saved: Awaited<ReturnType<VaultService["saveForAgent"]>> | null = null;
+      for (const item of [base, `${base} ${credential.credentialId.slice(-6)}`]) {
+        try {
+          saved = await vaults().saveForAgent(principal, {
+            item: safeName(item),
+            type: "passkey",
+            websites: origin ? [origin] : [`https://${credential.rpId}`],
+            fields,
+            mode: "create",
+          });
+          break;
+        } catch (error) {
+          if (isVaultError(error) && error.code === "vault_item_name_conflict") continue;
+          throw error;
+        }
+      }
+      if (!saved) throw new Error("could not name the new passkey item");
+      if (credential.signCount > 0) {
+        await updatePasskeySignCount(deps.db, context(principal), {
+          itemId: saved.item.id,
+          count: credential.signCount,
+        });
+      }
+      return { itemId: saved.item.id };
+    },
+    async updateSignCount(principal, itemId, signCount) {
+      await updatePasskeySignCount(deps.db, context(principal), { itemId, count: signCount });
+    },
+    async release(holder) {
+      const principal = holders.get(holder);
+      // Without the leasing principal (another API replica or a restart) the
+      // lease simply expires after its TTL.
+      if (!principal) return;
+      holders.delete(holder);
+      await releaseVaultPasskeyLeases(deps.db, context(principal), { holder });
+    },
+  };
+
+  return {
+    async resolverFor(principal): Promise<SecretResolver | null> {
+      const providersFor = deps.providersFor;
+      return createSecretResolver({ db: deps.db, encryptionKey }, principal, {
+        capabilityEnabled: await secretsEnabled(principal),
+        ...(providersFor
+          ? {
+              providersForSubject: (subjectId: string | null) =>
+                providersFor(principal.workspaceId, subjectId),
+            }
+          : {}),
+      });
+    },
+    passkeys,
+  };
+}

package/src/interaction-secrets.ts

@@ -0,0 +1,426 @@
+/**
+ * `{{secret:…}}` references in Browser and Computer actions (design §10B.4,
+ * BR-1..3). Only agent attempts resolve: the API resolves the references in
+ * the secret-bearing fields of an action right before dispatch and sends the
+ * plaintext to the controller in the private `secretValues` side map. Human
+ * and service callers' text is always typed literally. Agent-owned passkeys
+ * ride the same seam: around every agent browser action the API loads the
+ * principal's leased passkeys into browserd and pulls registration and
+ * assertion events back into the vault.
+ */
+import {
+  type AccessGrant,
+  type BrowserPasskeyCredential,
+  type BrowserPasskeyCredentialMaterial,
+  type BrowserPasskeyEvent,
+  type BrowserPasskeySyncRequest,
+  type BrowserPasskeySyncResponse,
+  buildMissingSecretAskCard,
+  containsSecretReference,
+  findInvalidSecretReferences,
+  findSecretReferences,
+  type InteractionSecretValues,
+  INTERACTION_PROTOCOL_VERSION,
+  isSecretReferenceError,
+  referenceKey,
+  type SecretClock,
+  SecretReferenceError,
+  type SecretReferenceFailure,
+  type SecretPrincipal,
+  type SecretResolver,
+  type SecretUseContext,
+  secretValueAtDispatch,
+} from "@opengeni/contracts";
+import { ApiHttpError } from "./http/api-error";
+
+export type AttemptSecretPrincipal = Extract<SecretPrincipal, { kind: "attempt" }>;
+
+/** Vault storage for agent-owned passkeys (F2: `lease_vault_passkeys`,
+ * `update_passkey_sign_count`, `release_vault_passkey_leases`). */
+export interface InteractionPasskeyStore {
+  /** Lease every passkey item the principal may use and no other holder holds. */
+  lease(
+    principal: AttemptSecretPrincipal,
+    holder: string,
+    ttlSeconds: number,
+  ): Promise<BrowserPasskeyCredential[]>;
+  /** Save a passkey the agent just registered; returns the new item. */
+  saveRegistered(
+    principal: AttemptSecretPrincipal,
+    input: { credential: BrowserPasskeyCredentialMaterial; origin: string | null },
+  ): Promise<{ itemId: string }>;
+  /** Monotonic write-back (`greatest(existing, new)`). */
+  updateSignCount(
+    principal: AttemptSecretPrincipal,
+    itemId: string,
+    signCount: number,
+  ): Promise<void>;
+  release(holder: string): Promise<void>;
+}
+
+export interface InteractionSecretsPort {
+  /** The principal's resolver, or null when secrets are unavailable here.
+   * A resolver with `enabled: false` (capability off) also passes text through
+   * literally (Q-35). */
+  resolverFor(principal: AttemptSecretPrincipal): Promise<SecretResolver | null>;
+  passkeys: InteractionPasskeyStore | null;
+  clock?: SecretClock;
+}
+
+export type InteractionSecretsLog = (event: string, fields: Record<string, unknown>) => void;
+
+/** The attempt principal of an agent grant. Human, service and incomplete
+ * grants have none, so their text is never resolved (BR-1). */
+export function attemptSecretPrincipal(grant: AccessGrant): AttemptSecretPrincipal | null {
+  if (grant.principalKind !== "agent_attempt") return null;
+  const metadata = grant.metadata ?? {};
+  const sessionId = metadata["sessionId"];
+  const turnId = metadata["turnId"];
+  const attemptId = metadata["attemptId"];
+  const executionGeneration = metadata["executionGeneration"];
+  if (
+    typeof sessionId !== "string" ||
+    typeof turnId !== "string" ||
+    typeof attemptId !== "string" ||
+    typeof executionGeneration !== "number" ||
+    !Number.isSafeInteger(executionGeneration)
+  ) {
+    return null;
+  }
+  return {
+    kind: "attempt",
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    sessionId,
+    turnId,
+    attemptId,
+    executionGeneration,
+  };
+}
+
+/** The public failure: nothing was dispatched. `details.secretReference` is
+ * the model-facing `{error, failures, askCard, hint}` object; it never
+ * contains values. */
+export function secretReferenceHttpError(error: SecretReferenceError): ApiHttpError {
+  const output = JSON.parse(error.toModelOutput()) as Record<string, unknown>;
+  return new ApiHttpError(422, {
+    code: "validation_failed",
+    message: `${error.message}. ${String(output["hint"] ?? "")}`.trim(),
+    retryable: false,
+    outcomeUnknown: false,
+    details: { reason: "secret_reference_error", secretReference: output },
+  });
+}
+
+function referenceFailure(
+  raw: string,
+  code: SecretReferenceFailure["code"],
+  message: string,
+): SecretReferenceFailure {
+  return { raw, code, message };
+}
+
+/** Every string in a JSON-like value (native desktop call arguments). */
+export function collectStringsDeep(value: unknown, out: string[] = [], depth = 0): string[] {
+  if (depth > 32) return out;
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value))
+    for (const entry of value) collectStringsDeep(entry, out, depth + 1);
+  else if (value !== null && typeof value === "object") {
+    for (const entry of Object.values(value)) collectStringsDeep(entry, out, depth + 1);
+  }
+  return out;
+}
+
+/**
+ * Resolve the references in `texts` for an agent grant. Returns undefined
+ * when the text must be dispatched literally (non-agent caller, no marker,
+ * secrets unavailable or off). Returns a (possibly empty) side map otherwise;
+ * an empty map still tells the controller to remove `\{{secret:…}}` escapes.
+ * TOTP codes are computed last, at dispatch (Q-33). Throws ApiHttpError(422)
+ * before anything is dispatched when any reference fails (I2).
+ */
+export async function resolveInteractionSecretValues(input: {
+  port: InteractionSecretsPort | null | undefined;
+  grant: AccessGrant;
+  texts: readonly string[];
+  use: SecretUseContext;
+  /** Runs once the text is known to carry references for an agent with
+   * secrets enabled, before anything resolves: a controller that cannot
+   * accept secret values refuses here, with nothing used or dispatched. */
+  beforeResolve?: () => Promise<void>;
+}): Promise<InteractionSecretValues | undefined> {
+  const { port, grant, texts, use, beforeResolve } = input;
+  if (!port) return undefined;
+  if (!texts.some((text) => containsSecretReference(text))) return undefined;
+  const principal = attemptSecretPrincipal(grant);
+  if (!principal) return undefined;
+  const resolver = await port.resolverFor(principal);
+  if (!resolver || !resolver.enabled) return undefined;
+  await beforeResolve?.();
+  const failures: SecretReferenceFailure[] = [];
+  for (const text of texts) {
+    for (const invalid of findInvalidSecretReferences(text)) {
+      failures.push(
+        referenceFailure(invalid.raw, "invalid_reference", `invalid reference: ${invalid.reason}`),
+      );
+    }
+  }
+  const references = texts.flatMap((text) => findSecretReferences(text));
+  for (const reference of references) {
+    if (reference.kind === "secretfile") {
+      failures.push(
+        referenceFailure(
+          reference.raw,
+          "secretfile_not_allowed",
+          "{{secretfile:…}} is for commands that read a file path; type the value with {{secret:…}}",
+        ),
+      );
+    }
+  }
+  if (failures.length > 0) throw secretReferenceHttpError(new SecretReferenceError(failures));
+  if (references.length === 0) return {};
+  let resolved;
+  try {
+    resolved = await resolver.resolve(references, use);
+  } catch (error) {
+    if (isSecretReferenceError(error)) {
+      if (error instanceof SecretReferenceError) throw secretReferenceHttpError(error);
+      // A structurally equal error from another copy of the contracts module.
+      const foreign = error as unknown as {
+        failures: SecretReferenceFailure[];
+        askCard?: SecretReferenceError["askCard"];
+      };
+      throw secretReferenceHttpError(
+        new SecretReferenceError(
+          foreign.failures,
+          foreign.askCard ?? buildMissingSecretAskCard(foreign.failures, { hasActingHuman: false }),
+        ),
+      );
+    }
+    throw error;
+  }
+  const values: InteractionSecretValues = {};
+  const ordered = [...resolved.values()].sort(
+    (left, right) => Number(left.material.type === "totp") - Number(right.material.type === "totp"),
+  );
+  for (const value of ordered) {
+    const material = await secretValueAtDispatch(value, port.clock);
+    if (typeof material !== "string") {
+      failures.push(
+        referenceFailure(
+          value.reference.raw,
+          "binary_value",
+          "this field holds a file; browsers and desktops can only type text",
+        ),
+      );
+      continue;
+    }
+    values[value.key] = material;
+  }
+  if (failures.length > 0) throw secretReferenceHttpError(new SecretReferenceError(failures));
+  for (const reference of references) {
+    if (values[referenceKey(reference)] === undefined) {
+      throw secretReferenceHttpError(
+        new SecretReferenceError([
+          referenceFailure(reference.raw, "not_found", "the reference did not resolve"),
+        ]),
+      );
+    }
+  }
+  return values;
+}
+
+// ---------------------------------------------------------------------------
+// Passkeys
+// ---------------------------------------------------------------------------
+
+export const PASSKEY_LEASE_TTL_SECONDS = 600;
+const PASSKEY_LEASE_RENEW_MS = 60_000;
+const PASSKEY_SESSION_CACHE_LIMIT = 2_048;
+
+type PasskeySessionState = {
+  leasedAtMs: number;
+  credentials: BrowserPasskeyCredential[];
+  unsupported: boolean;
+};
+
+/** Per-process lease cache: renew at most once a minute per browser session
+ * (leases last ten minutes and renew on use, Q-32). */
+const passkeySessions = new Map<string, PasskeySessionState>();
+
+/** The latest pending sync per BrowserSession; later syncs chain after it. */
+const passkeySyncTails = new Map<string, Promise<void>>();
+
+export function resetPasskeySessionCacheForTests(): void {
+  passkeySessions.clear();
+  passkeySyncTails.clear();
+}
+
+/** One lease holder per BrowserSession: every target in it shares the set. */
+export function passkeyLeaseHolder(browserSessionId: string): string {
+  return browserSessionId;
+}
+
+export type PasskeySyncClient = {
+  passkeySync(request: BrowserPasskeySyncRequest): Promise<BrowserPasskeySyncResponse>;
+};
+
+function isUnsupportedSync(error: unknown): boolean {
+  const status = (error as { status?: unknown } | null)?.status;
+  const name = (error as { name?: unknown } | null)?.name;
+  return status === 404 || status === 405 || name === "BrowserControlUnsupportedError";
+}
+
+/**
+ * Load the principal's passkeys into the BrowserSession and write back what
+ * happened since the last sync. Best effort: a failure is logged and never
+ * fails the surrounding action. Unacknowledged events stay in browserd and
+ * are retried on the next sync.
+ *
+ * Syncs for one BrowserSession run one at a time, in call order, so a caller
+ * may start the write-back after an action without awaiting it: the next
+ * action's sync waits for it instead of racing it on the same events.
+ */
+export function syncBrowserPasskeys(input: PasskeySyncInput): Promise<PasskeySyncResult> {
+  const previous = passkeySyncTails.get(input.browserSessionId);
+  const run = (previous ?? Promise.resolve()).then(() => syncBrowserPasskeysNow(input));
+  const tail = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  passkeySyncTails.set(input.browserSessionId, tail);
+  void tail.then(() => {
+    if (passkeySyncTails.get(input.browserSessionId) === tail) {
+      passkeySyncTails.delete(input.browserSessionId);
+    }
+  });
+  return run;
+}
+
+type PasskeySyncResult = { saved: number; asserted: number } | null;
+
+type PasskeySyncInput = {
+  port: InteractionSecretsPort | null | undefined;
+  grant: AccessGrant;
+  browserSessionId: string;
+  controllerGeneration: string;
+  client: PasskeySyncClient;
+  /** Lease again now (right before an action), taking over from any other browser. */
+  refresh?: boolean;
+  now?: () => number;
+  log?: InteractionSecretsLog;
+};
+
+async function syncBrowserPasskeysNow(input: PasskeySyncInput): Promise<PasskeySyncResult> {
+  const store = input.port?.passkeys;
+  if (!store) return null;
+  const principal = attemptSecretPrincipal(input.grant);
+  if (!principal) return null;
+  const now = input.now ?? Date.now;
+  const holder = passkeyLeaseHolder(input.browserSessionId);
+  // Per attempt: a later turn may act for another person, so it leases (and
+  // replaces browserd's credential set with) its own passkeys first.
+  const cacheKey = `${input.browserSessionId}:${input.controllerGeneration}:${principal.attemptId}`;
+  let state = passkeySessions.get(cacheKey);
+  if (state?.unsupported) return null;
+  const lease = async (): Promise<BrowserPasskeyCredential[]> => {
+    const credentials = await store.lease(principal, holder, PASSKEY_LEASE_TTL_SECONDS);
+    state = { leasedAtMs: now(), credentials, unsupported: false };
+    passkeySessions.delete(cacheKey);
+    passkeySessions.set(cacheKey, state);
+    while (passkeySessions.size > PASSKEY_SESSION_CACHE_LIMIT) {
+      passkeySessions.delete(passkeySessions.keys().next().value!);
+    }
+    return credentials;
+  };
+  const request = (
+    credentials: BrowserPasskeyCredential[] | null,
+    acknowledgeEventIds: string[],
+  ): BrowserPasskeySyncRequest => ({
+    protocolVersion: INTERACTION_PROTOCOL_VERSION,
+    browserSessionId: input.browserSessionId,
+    controllerGeneration: input.controllerGeneration,
+    credentials,
+    acknowledgeEventIds,
+  });
+  try {
+    const due =
+      input.refresh === true || !state || now() - state.leasedAtMs >= PASSKEY_LEASE_RENEW_MS;
+    const credentials = due ? await lease() : null;
+    let response: BrowserPasskeySyncResponse;
+    try {
+      response = await input.client.passkeySync(request(credentials, []));
+    } catch (error) {
+      if (isUnsupportedSync(error)) {
+        passkeySessions.set(cacheKey, {
+          leasedAtMs: now(),
+          credentials: [],
+          unsupported: true,
+        });
+        await store.release(holder).catch(() => undefined);
+        return null;
+      }
+      throw error;
+    }
+    if (response.events.length === 0) return { saved: 0, asserted: 0 };
+    const processed: string[] = [];
+    const itemByCredential = new Map(
+      (state?.credentials ?? []).map((credential) => [credential.credentialId, credential.itemId]),
+    );
+    let saved = 0;
+    let asserted = 0;
+    for (const event of response.events as BrowserPasskeyEvent[]) {
+      try {
+        if (event.type === "registered") {
+          const existing = itemByCredential.get(event.credential.credentialId);
+          if (existing === undefined) {
+            const result = await store.saveRegistered(principal, {
+              credential: event.credential,
+              origin: event.origin,
+            });
+            itemByCredential.set(event.credential.credentialId, result.itemId);
+            saved += 1;
+          }
+        } else {
+          const itemId = event.itemId ?? itemByCredential.get(event.credentialId) ?? null;
+          if (itemId !== null) {
+            await store.updateSignCount(principal, itemId, event.signCount);
+            asserted += 1;
+          } else {
+            input.log?.("browser.passkey.assertion_unmatched", { rpId: event.rpId });
+          }
+        }
+        processed.push(event.eventId);
+      } catch (error) {
+        input.log?.("browser.passkey.event_failed", {
+          type: event.type,
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    // New items are loaded with their item IDs so later assertions write back.
+    const refreshed = saved > 0 ? await lease() : null;
+    await input.client.passkeySync(request(refreshed, processed));
+    if (saved > 0 || asserted > 0) {
+      input.log?.("browser.passkey.synced", { saved, asserted });
+    }
+    return { saved, asserted };
+  } catch (error) {
+    input.log?.("browser.passkey.sync_failed", {
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}
+
+/** Release the BrowserSession's passkey leases (session end). Best effort. */
+export async function releaseBrowserPasskeys(
+  port: InteractionSecretsPort | null | undefined,
+  browserSessionId: string,
+): Promise<void> {
+  for (const key of [...passkeySessions.keys()]) {
+    if (key.startsWith(`${browserSessionId}:`)) passkeySessions.delete(key);
+  }
+  await port?.passkeys?.release(passkeyLeaseHolder(browserSessionId)).catch(() => undefined);
+}

package/src/mcp/action-catalog-types.ts

@@ -0,0 +1,14 @@
+export type ActionCatalogEntry = {
+  /** Stable name an agent calls: the SDK method ("listSessions"), else "METHOD /path". */
+  id: string;
+  method: string;
+  path: string;
+  /** Contract schema names for the JSON body and response, when known. */
+  request: string[];
+  response: string[];
+  /**
+   * Why no MCP caller can complete this action: it needs the person's own
+   * Opengeni browser session. Set only on such actions; the server hides them.
+   */
+  browserOnly?: string;
+};