@agimon-ai/po-core 0.0.0-alpha.0

package/dist/src/services/deviceTrust/index.mjs

@@ -0,0 +1,282 @@
+import { DEVICE_AUTH_CHALLENGE_TTL_MS, DEVICE_CHALLENGE_LIMIT, DEVICE_STEP_UP_CHALLENGE_TTL_MS, DEVICE_STEP_UP_TAG } from "../../constants/remote.mjs";
+import { sanitizeUserAgent } from "../deviceSessions/index.mjs";
+import { isStepUpAction } from "../webauthnPolicy/index.mjs";
+import { createPublicKey, randomBytes } from "node:crypto";
+import { verifyDeviceSignature } from "@agimon-ai/po-web-security/node";
+//#region src/services/deviceTrust/index.ts
+/**
+* Native device trust: message layout, key checks, and single-use challenges.
+*
+* A phone paired by QR registers two P-256 keys over the sealed gateway: an
+* identity key that signs silent reconnects, and a step-up key that only
+* biometrics unlock. Every signed message is `tag + "\n" + JSON.stringify(fields)`
+* with the fields in the fixed order below, so the phone and the host build the
+* same bytes and no message can be passed off as another or as a manifest.
+*
+* No I/O and no hidden clock: the caller passes the clock, the challenge store,
+* and the record lookup, so every rule here is testable without a server.
+*/
+/** Challenges and nonces are 32 random bytes, which is 43 base64url characters. */
+const RANDOM_BYTES = 32;
+const RANDOM_VALUE = /^[A-Za-z0-9_-]{43}$/u;
+const CHALLENGE_ID_BYTES = 16;
+/** Opaque ids: trusted device ids, session device ids, and challenge ids. */
+const OPAQUE_ID = /^[A-Za-z0-9_-]{1,64}$/u;
+const MAX_SPKI_LENGTH = 512;
+const MAX_CHANNEL_KEY_LENGTH = 128;
+const MAX_SIGNATURE_LENGTH = 128;
+const BASE64URL = /^[A-Za-z0-9_-]+$/u;
+const P256_CURVE = "prime256v1";
+const PLATFORMS = /* @__PURE__ */ new Set(["ios", "android"]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isBase64Url(value, maximum) {
+	return typeof value === "string" && value.length > 0 && value.length <= maximum && BASE64URL.test(value);
+}
+function ttlOf(purpose) {
+	return purpose.kind === "auth" ? DEVICE_AUTH_CHALLENGE_TTL_MS : DEVICE_STEP_UP_CHALLENGE_TTL_MS;
+}
+/** `po/host-channel-key/v1`, signed by the host bundle signer. */
+function hostChannelKeyFields(origin, hostPublicKey, deviceNonce) {
+	return [
+		origin,
+		hostPublicKey,
+		deviceNonce
+	];
+}
+/** `po/device-register/v1`, signed by the identity key and separately by the step-up key. */
+function deviceRegisterFields(input) {
+	return [
+		input.origin,
+		input.hostPublicKey,
+		input.sessionDeviceId,
+		input.identityPublicKey,
+		input.stepUpPublicKey,
+		input.platform
+	];
+}
+/** `po/device-auth/v1`, signed by the identity key. All three channel keys are covered. */
+function deviceAuthFields(input) {
+	return [
+		input.origin,
+		input.challenge,
+		input.hostPublicKey,
+		input.trustedDeviceId,
+		input.channels.session,
+		input.channels.protocol,
+		input.channels.http
+	];
+}
+/** `po/device-step-up/v1`, signed by the biometric step-up key. */
+function deviceStepUpFields(input) {
+	return [
+		input.origin,
+		input.action,
+		input.sessionDeviceId,
+		input.challengeId,
+		input.challenge
+	];
+}
+/** Whether a value is a base64url DER SPKI for an EC P-256 public key, the only kind a device may register. */
+function isP256PublicKey(value) {
+	if (!isBase64Url(value, MAX_SPKI_LENGTH)) return false;
+	try {
+		const key = createPublicKey({
+			key: Buffer.from(value, "base64url"),
+			format: "der",
+			type: "spki"
+		});
+		return key.asymmetricKeyType === "ec" && key.asymmetricKeyDetails?.namedCurve === P256_CURVE;
+	} catch {
+		return false;
+	}
+}
+/** Whether a value is a fresh-looking 32-byte base64url nonce. */
+function isDeviceNonce(value) {
+	return typeof value === "string" && RANDOM_VALUE.test(value);
+}
+function isOpaqueId(value) {
+	return typeof value === "string" && OPAQUE_ID.test(value);
+}
+/**
+* Single-use challenges, bounded in count and lifetime.
+*
+* Deleted on first `take`, whatever the outcome of the check that follows, so a
+* challenge cannot be retried. Expired entries are swept on every issue, and the
+* oldest entry goes when the store is full.
+*/
+function createDeviceChallenges(options) {
+	const random = options.random ?? ((bytes) => randomBytes(bytes).toString("base64url"));
+	const pending = /* @__PURE__ */ new Map();
+	const live = (entry, at) => at - entry.issuedAt < ttlOf(entry.purpose);
+	return {
+		issue(hostPublicKey, purpose) {
+			const at = options.now();
+			for (const [id, entry] of pending) if (!live(entry, at)) pending.delete(id);
+			while (pending.size >= DEVICE_CHALLENGE_LIMIT) {
+				const oldest = pending.keys().next().value;
+				if (oldest === void 0) break;
+				pending.delete(oldest);
+			}
+			const entry = {
+				id: random(CHALLENGE_ID_BYTES),
+				challenge: random(RANDOM_BYTES),
+				hostPublicKey,
+				issuedAt: at,
+				purpose
+			};
+			pending.set(entry.id, entry);
+			return entry;
+		},
+		take(id) {
+			const entry = pending.get(id);
+			if (entry === void 0) return void 0;
+			pending.delete(id);
+			return live(entry, options.now()) ? entry : void 0;
+		},
+		dropWhere(predicate) {
+			for (const [id, entry] of pending) if (predicate(entry)) pending.delete(id);
+		},
+		clear: () => pending.clear(),
+		size: () => pending.size
+	};
+}
+/**
+* The public reconnect challenge.
+*
+* It never consults the trusted-device list, so a known id and an unknown one
+* produce the same shape and the route cannot be used to enumerate devices.
+* The attestation proves the fresh tunnel key with the signer the phone pinned
+* at pairing, over the phone's own nonce. Undefined while the host cannot attest.
+*/
+function deviceAuthChallenge(input) {
+	const attestation = input.attest(hostChannelKeyFields(input.origin, input.hostPublicKey, input.nonce));
+	if (attestation === void 0) return void 0;
+	const issued = input.challenges.issue(input.hostPublicKey, {
+		kind: "auth",
+		trustedDeviceId: input.trustedDeviceId
+	});
+	return {
+		challengeId: issued.id,
+		challenge: issued.challenge,
+		hostPublicKey: input.hostPublicKey,
+		attestation
+	};
+}
+/** A step-up challenge bound to one action and one session, answered by the biometric key. */
+function deviceStepUpChallenge(input) {
+	const issued = input.challenges.issue(input.hostPublicKey, {
+		kind: "step-up",
+		sessionDeviceId: input.sessionDeviceId,
+		action: input.action
+	});
+	return {
+		ceremonyId: issued.id,
+		challenge: issued.challenge,
+		kind: "device-key"
+	};
+}
+/**
+* Checks a registration from a sealed `pairing` session.
+*
+* Both keys must be distinct P-256 SPKIs and both must sign the same
+* `po/device-register/v1` message, which binds them to this origin, this
+* tunnel key, and this exact session.
+*/
+function verifyRegistration(input) {
+	if (input.trust?.kind !== "pairing") return {
+		ok: false,
+		reason: "not-pairing"
+	};
+	const body = input.body;
+	if (!isRecord(body)) return {
+		ok: false,
+		reason: "invalid"
+	};
+	const { identityPublicKey, stepUpPublicKey, label, platform, identityProof, stepUpProof } = body;
+	if (!isP256PublicKey(identityPublicKey) || !isP256PublicKey(stepUpPublicKey) || identityPublicKey === stepUpPublicKey || typeof label !== "string" || typeof platform !== "string" || !PLATFORMS.has(platform) || !isBase64Url(identityProof, MAX_SIGNATURE_LENGTH) || !isBase64Url(stepUpProof, MAX_SIGNATURE_LENGTH)) return {
+		ok: false,
+		reason: "invalid"
+	};
+	const fields = deviceRegisterFields({
+		origin: input.origin,
+		hostPublicKey: input.hostPublicKey,
+		sessionDeviceId: input.sessionDeviceId,
+		identityPublicKey,
+		stepUpPublicKey,
+		platform
+	});
+	if (!verifyDeviceSignature(identityPublicKey, "po/device-register/v1", fields, identityProof) || !verifyDeviceSignature(stepUpPublicKey, "po/device-register/v1", fields, stepUpProof)) return {
+		ok: false,
+		reason: "invalid"
+	};
+	return {
+		ok: true,
+		identityPublicKey,
+		stepUpPublicKey,
+		label: sanitizeUserAgent(label),
+		platform
+	};
+}
+function channelKeysOf(value) {
+	if (!isRecord(value)) return void 0;
+	const { session, protocol, http } = value;
+	if (!isBase64Url(session, MAX_CHANNEL_KEY_LENGTH) || !isBase64Url(protocol, MAX_CHANNEL_KEY_LENGTH) || !isBase64Url(http, MAX_CHANNEL_KEY_LENGTH)) return void 0;
+	if (session === protocol || session === http || protocol === http) return void 0;
+	return {
+		session,
+		protocol,
+		http
+	};
+}
+/**
+* Checks a device sign-in. The challenge is consumed before anything else is
+* looked at, so every attempt, good or bad, burns it.
+*/
+function verifyAuthentication(input) {
+	const body = input.body;
+	if (!isRecord(body) || !isOpaqueId(body.challengeId)) return { ok: false };
+	const issued = input.challenges.take(body.challengeId);
+	if (issued === void 0 || issued.purpose.kind !== "auth") return { ok: false };
+	if (input.hostPublicKey === void 0 || issued.hostPublicKey !== input.hostPublicKey) return { ok: false };
+	if (!isOpaqueId(body.trustedDeviceId) || body.trustedDeviceId !== issued.purpose.trustedDeviceId) return { ok: false };
+	if (!isBase64Url(body.signature, MAX_SIGNATURE_LENGTH)) return { ok: false };
+	const channels = channelKeysOf(body.channels);
+	if (channels === void 0) return { ok: false };
+	const record = input.find(body.trustedDeviceId);
+	if (record === void 0) return { ok: false };
+	const fields = deviceAuthFields({
+		origin: input.origin,
+		challenge: issued.challenge,
+		hostPublicKey: issued.hostPublicKey,
+		trustedDeviceId: record.id,
+		channels
+	});
+	if (!verifyDeviceSignature(record.identityPublicKey, "po/device-auth/v1", fields, body.signature)) return { ok: false };
+	return {
+		ok: true,
+		record,
+		channels
+	};
+}
+/** Checks a biometric step-up signature for one action from one device-key session. */
+function verifyStepUp(input) {
+	if (!isOpaqueId(input.ceremonyId) || !isStepUpAction(input.action)) return false;
+	const issued = input.challenges.take(input.ceremonyId);
+	if (issued === void 0 || issued.purpose.kind !== "step-up") return false;
+	if (input.hostPublicKey === void 0 || issued.hostPublicKey !== input.hostPublicKey) return false;
+	if (issued.purpose.sessionDeviceId !== input.sessionDeviceId || issued.purpose.action !== input.action) return false;
+	if (!isBase64Url(input.signature, MAX_SIGNATURE_LENGTH)) return false;
+	return verifyDeviceSignature(input.stepUpPublicKey, DEVICE_STEP_UP_TAG, deviceStepUpFields({
+		origin: input.origin,
+		action: input.action,
+		sessionDeviceId: input.sessionDeviceId,
+		challengeId: issued.id,
+		challenge: issued.challenge
+	}), input.signature);
+}
+//#endregion
+export { createDeviceChallenges, deviceAuthChallenge, deviceAuthFields, deviceRegisterFields, deviceStepUpChallenge, deviceStepUpFields, hostChannelKeyFields, isDeviceNonce, isOpaqueId, isP256PublicKey, verifyAuthentication, verifyRegistration, verifyStepUp };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/deviceTrust/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/deviceTrust/index.ts"],"sourcesContent":["/**\n * Native device trust: message layout, key checks, and single-use challenges.\n *\n * A phone paired by QR registers two P-256 keys over the sealed gateway: an\n * identity key that signs silent reconnects, and a step-up key that only\n * biometrics unlock. Every signed message is `tag + \"\\n\" + JSON.stringify(fields)`\n * with the fields in the fixed order below, so the phone and the host build the\n * same bytes and no message can be passed off as another or as a manifest.\n *\n * No I/O and no hidden clock: the caller passes the clock, the challenge store,\n * and the record lookup, so every rule here is testable without a server.\n */\n\nimport { createPublicKey, randomBytes } from 'node:crypto';\n\nimport { verifyDeviceSignature } from '@agimon-ai/po-web-security/node';\n\nimport {\n  DEVICE_AUTH_CHALLENGE_TTL_MS,\n  DEVICE_AUTH_TAG,\n  DEVICE_CHALLENGE_LIMIT,\n  DEVICE_REGISTER_TAG,\n  DEVICE_STEP_UP_CHALLENGE_TTL_MS,\n  DEVICE_STEP_UP_TAG,\n} from '../../constants/remote';\nimport type { DeviceTrust, TrustedDevicePlatform, TrustedDeviceRecord } from '../../types/remote';\nimport { sanitizeUserAgent } from '../deviceSessions';\nimport { isStepUpAction, type StepUpAction } from '../webauthnPolicy';\n\n/** Challenges and nonces are 32 random bytes, which is 43 base64url characters. */\nconst RANDOM_BYTES = 32;\nconst RANDOM_VALUE = /^[A-Za-z0-9_-]{43}$/u;\nconst CHALLENGE_ID_BYTES = 16;\n/** Opaque ids: trusted device ids, session device ids, and challenge ids. */\nconst OPAQUE_ID = /^[A-Za-z0-9_-]{1,64}$/u;\nconst MAX_SPKI_LENGTH = 512;\nconst MAX_CHANNEL_KEY_LENGTH = 128;\nconst MAX_SIGNATURE_LENGTH = 128;\nconst BASE64URL = /^[A-Za-z0-9_-]+$/u;\nconst P256_CURVE = 'prime256v1';\nconst PLATFORMS: ReadonlySet<string> = new Set<TrustedDevicePlatform>(['ios', 'android']);\n\nexport type DeviceChallengePurpose =\n  | { kind: 'auth'; trustedDeviceId: string }\n  | { kind: 'step-up'; sessionDeviceId: string; action: StepUpAction };\n\nexport interface DeviceChallenge {\n  id: string;\n  challenge: string;\n  /** The tunnel key in force when the challenge was issued; it must still be the current one. */\n  hostPublicKey: string;\n  issuedAt: number;\n  purpose: DeviceChallengePurpose;\n}\n\nexport interface DeviceChallenges {\n  issue(hostPublicKey: string, purpose: DeviceChallengePurpose): DeviceChallenge;\n  /** Removes and returns a live challenge. Undefined when unknown, already used, or expired. */\n  take(id: string): DeviceChallenge | undefined;\n  /** Drops every challenge the predicate selects, such as those of a revoked device. */\n  dropWhere(predicate: (challenge: DeviceChallenge) => boolean): void;\n  clear(): void;\n  size(): number;\n}\n\nexport interface DeviceChallengesOptions {\n  now: () => number;\n  /** Base64url random value of the given byte length; injectable for tests. */\n  random?: (bytes: number) => string;\n}\n\nexport interface DeviceChannelKeys {\n  session: string;\n  protocol: string;\n  http: string;\n}\n\nexport type RegistrationVerdict =\n  | {\n      ok: true;\n      identityPublicKey: string;\n      stepUpPublicKey: string;\n      label: string;\n      platform: TrustedDevicePlatform;\n    }\n  | { ok: false; reason: 'not-pairing' | 'invalid' };\n\nexport type AuthenticationVerdict =\n  | { ok: true; record: TrustedDeviceRecord; channels: DeviceChannelKeys }\n  | { ok: false };\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isBase64Url(value: unknown, maximum: number): value is string {\n  return typeof value === 'string' && value.length > 0 && value.length <= maximum && BASE64URL.test(value);\n}\n\nfunction ttlOf(purpose: DeviceChallengePurpose): number {\n  return purpose.kind === 'auth' ? DEVICE_AUTH_CHALLENGE_TTL_MS : DEVICE_STEP_UP_CHALLENGE_TTL_MS;\n}\n\n/** `po/host-channel-key/v1`, signed by the host bundle signer. */\nexport function hostChannelKeyFields(origin: string, hostPublicKey: string, deviceNonce: string): string[] {\n  return [origin, hostPublicKey, deviceNonce];\n}\n\n/** `po/device-register/v1`, signed by the identity key and separately by the step-up key. */\nexport function deviceRegisterFields(input: {\n  origin: string;\n  hostPublicKey: string;\n  sessionDeviceId: string;\n  identityPublicKey: string;\n  stepUpPublicKey: string;\n  platform: string;\n}): string[] {\n  return [\n    input.origin,\n    input.hostPublicKey,\n    input.sessionDeviceId,\n    input.identityPublicKey,\n    input.stepUpPublicKey,\n    input.platform,\n  ];\n}\n\n/** `po/device-auth/v1`, signed by the identity key. All three channel keys are covered. */\nexport function deviceAuthFields(input: {\n  origin: string;\n  challenge: string;\n  hostPublicKey: string;\n  trustedDeviceId: string;\n  channels: DeviceChannelKeys;\n}): string[] {\n  return [\n    input.origin,\n    input.challenge,\n    input.hostPublicKey,\n    input.trustedDeviceId,\n    input.channels.session,\n    input.channels.protocol,\n    input.channels.http,\n  ];\n}\n\n/** `po/device-step-up/v1`, signed by the biometric step-up key. */\nexport function deviceStepUpFields(input: {\n  origin: string;\n  action: string;\n  sessionDeviceId: string;\n  challengeId: string;\n  challenge: string;\n}): string[] {\n  return [input.origin, input.action, input.sessionDeviceId, input.challengeId, input.challenge];\n}\n\n/** Whether a value is a base64url DER SPKI for an EC P-256 public key, the only kind a device may register. */\nexport function isP256PublicKey(value: unknown): value is string {\n  if (!isBase64Url(value, MAX_SPKI_LENGTH)) return false;\n  try {\n    const key = createPublicKey({ key: Buffer.from(value, 'base64url'), format: 'der', type: 'spki' });\n    return key.asymmetricKeyType === 'ec' && key.asymmetricKeyDetails?.namedCurve === P256_CURVE;\n  } catch {\n    // Not a parseable SPKI, which is the answer: refuse it.\n    return false;\n  }\n}\n\n/** Whether a value is a fresh-looking 32-byte base64url nonce. */\nexport function isDeviceNonce(value: unknown): value is string {\n  return typeof value === 'string' && RANDOM_VALUE.test(value);\n}\n\nexport function isOpaqueId(value: unknown): value is string {\n  return typeof value === 'string' && OPAQUE_ID.test(value);\n}\n\n/**\n * Single-use challenges, bounded in count and lifetime.\n *\n * Deleted on first `take`, whatever the outcome of the check that follows, so a\n * challenge cannot be retried. Expired entries are swept on every issue, and the\n * oldest entry goes when the store is full.\n */\nexport function createDeviceChallenges(options: DeviceChallengesOptions): DeviceChallenges {\n  const random = options.random ?? ((bytes: number): string => randomBytes(bytes).toString('base64url'));\n  const pending = new Map<string, DeviceChallenge>();\n  const live = (entry: DeviceChallenge, at: number): boolean => at - entry.issuedAt < ttlOf(entry.purpose);\n\n  return {\n    issue(hostPublicKey, purpose) {\n      const at = options.now();\n      for (const [id, entry] of pending) if (!live(entry, at)) pending.delete(id);\n      while (pending.size >= DEVICE_CHALLENGE_LIMIT) {\n        const oldest = pending.keys().next().value;\n        if (oldest === undefined) break;\n        pending.delete(oldest);\n      }\n      const entry: DeviceChallenge = {\n        id: random(CHALLENGE_ID_BYTES),\n        challenge: random(RANDOM_BYTES),\n        hostPublicKey,\n        issuedAt: at,\n        purpose,\n      };\n      pending.set(entry.id, entry);\n      return entry;\n    },\n\n    take(id) {\n      const entry = pending.get(id);\n      if (entry === undefined) return undefined;\n      pending.delete(id);\n      return live(entry, options.now()) ? entry : undefined;\n    },\n\n    dropWhere(predicate) {\n      for (const [id, entry] of pending) if (predicate(entry)) pending.delete(id);\n    },\n\n    clear: () => pending.clear(),\n    size: () => pending.size,\n  };\n}\n\n/**\n * The public reconnect challenge.\n *\n * It never consults the trusted-device list, so a known id and an unknown one\n * produce the same shape and the route cannot be used to enumerate devices.\n * The attestation proves the fresh tunnel key with the signer the phone pinned\n * at pairing, over the phone's own nonce. Undefined while the host cannot attest.\n */\nexport function deviceAuthChallenge(input: {\n  challenges: DeviceChallenges;\n  trustedDeviceId: string;\n  nonce: string;\n  origin: string;\n  hostPublicKey: string;\n  attest: (fields: readonly string[]) => string | undefined;\n}): { challengeId: string; challenge: string; hostPublicKey: string; attestation: string } | undefined {\n  const attestation = input.attest(hostChannelKeyFields(input.origin, input.hostPublicKey, input.nonce));\n  if (attestation === undefined) return undefined;\n  const issued = input.challenges.issue(input.hostPublicKey, { kind: 'auth', trustedDeviceId: input.trustedDeviceId });\n  return { challengeId: issued.id, challenge: issued.challenge, hostPublicKey: input.hostPublicKey, attestation };\n}\n\n/** A step-up challenge bound to one action and one session, answered by the biometric key. */\nexport function deviceStepUpChallenge(input: {\n  challenges: DeviceChallenges;\n  sessionDeviceId: string;\n  action: StepUpAction;\n  hostPublicKey: string;\n}): { ceremonyId: string; challenge: string; kind: 'device-key' } {\n  const issued = input.challenges.issue(input.hostPublicKey, {\n    kind: 'step-up',\n    sessionDeviceId: input.sessionDeviceId,\n    action: input.action,\n  });\n  return { ceremonyId: issued.id, challenge: issued.challenge, kind: 'device-key' };\n}\n\n/**\n * Checks a registration from a sealed `pairing` session.\n *\n * Both keys must be distinct P-256 SPKIs and both must sign the same\n * `po/device-register/v1` message, which binds them to this origin, this\n * tunnel key, and this exact session.\n */\nexport function verifyRegistration(input: {\n  origin: string;\n  hostPublicKey: string;\n  sessionDeviceId: string;\n  trust: DeviceTrust | undefined;\n  body: unknown;\n}): RegistrationVerdict {\n  if (input.trust?.kind !== 'pairing') return { ok: false, reason: 'not-pairing' };\n  const body = input.body;\n  if (!isRecord(body)) return { ok: false, reason: 'invalid' };\n  const { identityPublicKey, stepUpPublicKey, label, platform, identityProof, stepUpProof } = body;\n  if (\n    !isP256PublicKey(identityPublicKey) ||\n    !isP256PublicKey(stepUpPublicKey) ||\n    identityPublicKey === stepUpPublicKey ||\n    typeof label !== 'string' ||\n    typeof platform !== 'string' ||\n    !PLATFORMS.has(platform) ||\n    !isBase64Url(identityProof, MAX_SIGNATURE_LENGTH) ||\n    !isBase64Url(stepUpProof, MAX_SIGNATURE_LENGTH)\n  )\n    return { ok: false, reason: 'invalid' };\n  const fields = deviceRegisterFields({\n    origin: input.origin,\n    hostPublicKey: input.hostPublicKey,\n    sessionDeviceId: input.sessionDeviceId,\n    identityPublicKey,\n    stepUpPublicKey,\n    platform,\n  });\n  if (\n    !verifyDeviceSignature(identityPublicKey, DEVICE_REGISTER_TAG, fields, identityProof) ||\n    !verifyDeviceSignature(stepUpPublicKey, DEVICE_REGISTER_TAG, fields, stepUpProof)\n  )\n    return { ok: false, reason: 'invalid' };\n  return {\n    ok: true,\n    identityPublicKey,\n    stepUpPublicKey,\n    // Attacker-supplied and shown in the host UI, so it is cleaned like a user agent.\n    label: sanitizeUserAgent(label),\n    platform: platform as TrustedDevicePlatform,\n  };\n}\n\nfunction channelKeysOf(value: unknown): DeviceChannelKeys | undefined {\n  if (!isRecord(value)) return undefined;\n  const { session, protocol, http } = value;\n  if (\n    !isBase64Url(session, MAX_CHANNEL_KEY_LENGTH) ||\n    !isBase64Url(protocol, MAX_CHANNEL_KEY_LENGTH) ||\n    !isBase64Url(http, MAX_CHANNEL_KEY_LENGTH)\n  )\n    return undefined;\n  if (session === protocol || session === http || protocol === http) return undefined;\n  return { session, protocol, http };\n}\n\n/**\n * Checks a device sign-in. The challenge is consumed before anything else is\n * looked at, so every attempt, good or bad, burns it.\n */\nexport function verifyAuthentication(input: {\n  challenges: DeviceChallenges;\n  origin: string;\n  /** The tunnel key in force now; a challenge issued under another one is refused. */\n  hostPublicKey: string | undefined;\n  find: (trustedDeviceId: string) => TrustedDeviceRecord | undefined;\n  body: unknown;\n}): AuthenticationVerdict {\n  const body = input.body;\n  if (!isRecord(body) || !isOpaqueId(body.challengeId)) return { ok: false };\n  const issued = input.challenges.take(body.challengeId);\n  if (issued === undefined || issued.purpose.kind !== 'auth') return { ok: false };\n  if (input.hostPublicKey === undefined || issued.hostPublicKey !== input.hostPublicKey) return { ok: false };\n  if (!isOpaqueId(body.trustedDeviceId) || body.trustedDeviceId !== issued.purpose.trustedDeviceId)\n    return { ok: false };\n  if (!isBase64Url(body.signature, MAX_SIGNATURE_LENGTH)) return { ok: false };\n  const channels = channelKeysOf(body.channels);\n  if (channels === undefined) return { ok: false };\n  const record = input.find(body.trustedDeviceId);\n  if (record === undefined) return { ok: false };\n  const fields = deviceAuthFields({\n    origin: input.origin,\n    challenge: issued.challenge,\n    hostPublicKey: issued.hostPublicKey,\n    trustedDeviceId: record.id,\n    channels,\n  });\n  if (!verifyDeviceSignature(record.identityPublicKey, DEVICE_AUTH_TAG, fields, body.signature)) return { ok: false };\n  return { ok: true, record, channels };\n}\n\n/** Checks a biometric step-up signature for one action from one device-key session. */\nexport function verifyStepUp(input: {\n  challenges: DeviceChallenges;\n  origin: string;\n  hostPublicKey: string | undefined;\n  sessionDeviceId: string;\n  action: string;\n  ceremonyId: unknown;\n  signature: unknown;\n  stepUpPublicKey: string;\n}): boolean {\n  if (!isOpaqueId(input.ceremonyId) || !isStepUpAction(input.action)) return false;\n  const issued = input.challenges.take(input.ceremonyId);\n  if (issued === undefined || issued.purpose.kind !== 'step-up') return false;\n  if (input.hostPublicKey === undefined || issued.hostPublicKey !== input.hostPublicKey) return false;\n  if (issued.purpose.sessionDeviceId !== input.sessionDeviceId || issued.purpose.action !== input.action) return false;\n  if (!isBase64Url(input.signature, MAX_SIGNATURE_LENGTH)) return false;\n  return verifyDeviceSignature(\n    input.stepUpPublicKey,\n    DEVICE_STEP_UP_TAG,\n    deviceStepUpFields({\n      origin: input.origin,\n      action: input.action,\n      sessionDeviceId: input.sessionDeviceId,\n      challengeId: issued.id,\n      challenge: issued.challenge,\n    }),\n    input.signature,\n  );\n}\n"],"mappings":"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"}

package/dist/src/services/durableNavigation/index.cjs

@@ -0,0 +1,46 @@
+//#region src/services/durableNavigation/index.ts
+/** External session identity is independent of the currently selected conversation. */
+const DurableNavigationDoc = (0, require("@earendil-works/pi-durable").defineDoc)({
+	kind: "po.navigation",
+	version: 1,
+	scope: "session",
+	initial: () => ({
+		activeConversationId: null,
+		branches: []
+	})
+});
+/** Select the initial conversation without overwriting a previously persisted selection. */
+async function initializeDurableNavigation(session, conversationId, context) {
+	return session.commit(async (tx) => {
+		if (!await tx.conversation(conversationId)) throw new Error("Initial conversation does not exist");
+		const navigation = await tx.doc(DurableNavigationDoc);
+		navigation.activeConversationId ??= conversationId;
+		return navigation.activeConversationId;
+	}, context);
+}
+/**
+* Fork the selected history, retaining its abandoned tail. A head marker alone cannot rewind.
+* The caller must settle active work and prepare any summary before entering this transaction.
+* Expected selection guards against a stale asynchronous summary switching a newer selection.
+*/
+async function navigateDurableConversation(session, expectedConversationId, targetId, context, options) {
+	return session.commit(async (tx) => {
+		const navigation = await tx.doc(DurableNavigationDoc);
+		if (navigation.activeConversationId !== expectedConversationId) throw new Error("The active conversation changed during navigation");
+		const next = targetId === null ? await tx.createConversation({ ownership: { kind: "ownerless" } }) : await tx.forkConversation(expectedConversationId, targetId, { ownership: { kind: "ownerless" } });
+		if (options?.summary) await tx.appendEntry(next.id, options.summary);
+		navigation.branches.push({
+			conversationId: next.id,
+			sourceConversationId: expectedConversationId,
+			targetId
+		});
+		navigation.activeConversationId = next.id;
+		return next.id;
+	}, context);
+}
+//#endregion
+exports.DurableNavigationDoc = DurableNavigationDoc;
+exports.initializeDurableNavigation = initializeDurableNavigation;
+exports.navigateDurableConversation = navigateDurableConversation;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/durableNavigation/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["defineDoc"],"sources":["../../../../src/services/durableNavigation/index.ts"],"sourcesContent":["import type { Context } from '@earendil-works/chord';\nimport {\n  defineDoc,\n  type ConversationId,\n  type EntryDraft,\n  type EntryId,\n  type Session,\n} from '@earendil-works/pi-durable';\n\n/** External session identity is independent of the currently selected conversation. */\nexport const DurableNavigationDoc = defineDoc<{\n  activeConversationId: ConversationId | null;\n  branches: { conversationId: ConversationId; sourceConversationId: ConversationId; targetId: EntryId | null }[];\n}>({\n  kind: 'po.navigation',\n  version: 1,\n  scope: 'session',\n  initial: () => ({ activeConversationId: null, branches: [] }),\n});\n\n/** Select the initial conversation without overwriting a previously persisted selection. */\nexport async function initializeDurableNavigation(\n  session: Session,\n  conversationId: ConversationId,\n  context: Context,\n): Promise<ConversationId> {\n  return session.commit(async (tx) => {\n    if (!(await tx.conversation(conversationId))) throw new Error('Initial conversation does not exist');\n    const navigation = await tx.doc(DurableNavigationDoc);\n    navigation.activeConversationId ??= conversationId;\n    return navigation.activeConversationId;\n  }, context);\n}\n\n/**\n * Fork the selected history, retaining its abandoned tail. A head marker alone cannot rewind.\n * The caller must settle active work and prepare any summary before entering this transaction.\n * Expected selection guards against a stale asynchronous summary switching a newer selection.\n */\nexport async function navigateDurableConversation(\n  session: Session,\n  expectedConversationId: ConversationId,\n  targetId: EntryId | null,\n  context: Context,\n  options?: { summary?: EntryDraft },\n): Promise<ConversationId> {\n  return session.commit(async (tx) => {\n    const navigation = await tx.doc(DurableNavigationDoc);\n    if (navigation.activeConversationId !== expectedConversationId)\n      throw new Error('The active conversation changed during navigation');\n    const next =\n      targetId === null\n        ? await tx.createConversation({ ownership: { kind: 'ownerless' } })\n        : await tx.forkConversation(expectedConversationId, targetId, { ownership: { kind: 'ownerless' } });\n    if (options?.summary) await tx.appendEntry(next.id, options.summary);\n    navigation.branches.push({\n      conversationId: next.id,\n      sourceConversationId: expectedConversationId,\n      targetId,\n    });\n    navigation.activeConversationId = next.id;\n    return next.id;\n  }, context);\n}\n"],"mappings":";;AAUA,MAAa,wBAAA,uCAAuBA,CAAAA,CAAAA,UAAAA,CAGjC;CACD,MAAM;CACN,SAAS;CACT,OAAO;CACP,gBAAgB;EAAE,sBAAsB;EAAM,UAAU,CAAC;CAAE;AAC7D,CAAC;;AAGD,eAAsB,4BACpB,SACA,gBACA,SACyB;CACzB,OAAO,QAAQ,OAAO,OAAO,OAAO;EAClC,IAAI,CAAE,MAAM,GAAG,aAAa,cAAc,GAAI,MAAM,IAAI,MAAM,qCAAqC;EACnG,MAAM,aAAa,MAAM,GAAG,IAAI,oBAAoB;EACpD,WAAW,yBAAyB;EACpC,OAAO,WAAW;CACpB,GAAG,OAAO;AACZ;;;;;;AAOA,eAAsB,4BACpB,SACA,wBACA,UACA,SACA,SACyB;CACzB,OAAO,QAAQ,OAAO,OAAO,OAAO;EAClC,MAAM,aAAa,MAAM,GAAG,IAAI,oBAAoB;EACpD,IAAI,WAAW,yBAAyB,wBACtC,MAAM,IAAI,MAAM,mDAAmD;EACrE,MAAM,OACJ,aAAa,OACT,MAAM,GAAG,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,EAAE,CAAC,IAChE,MAAM,GAAG,iBAAiB,wBAAwB,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,EAAE,CAAC;EACtG,IAAI,SAAS,SAAS,MAAM,GAAG,YAAY,KAAK,IAAI,QAAQ,OAAO;EACnE,WAAW,SAAS,KAAK;GACvB,gBAAgB,KAAK;GACrB,sBAAsB;GACtB;EACF,CAAC;EACD,WAAW,uBAAuB,KAAK;EACvC,OAAO,KAAK;CACd,GAAG,OAAO;AACZ"}

package/dist/src/services/durableNavigation/index.mjs

@@ -0,0 +1,45 @@
+import { defineDoc } from "@earendil-works/pi-durable";
+//#region src/services/durableNavigation/index.ts
+/** External session identity is independent of the currently selected conversation. */
+const DurableNavigationDoc = defineDoc({
+	kind: "po.navigation",
+	version: 1,
+	scope: "session",
+	initial: () => ({
+		activeConversationId: null,
+		branches: []
+	})
+});
+/** Select the initial conversation without overwriting a previously persisted selection. */
+async function initializeDurableNavigation(session, conversationId, context) {
+	return session.commit(async (tx) => {
+		if (!await tx.conversation(conversationId)) throw new Error("Initial conversation does not exist");
+		const navigation = await tx.doc(DurableNavigationDoc);
+		navigation.activeConversationId ??= conversationId;
+		return navigation.activeConversationId;
+	}, context);
+}
+/**
+* Fork the selected history, retaining its abandoned tail. A head marker alone cannot rewind.
+* The caller must settle active work and prepare any summary before entering this transaction.
+* Expected selection guards against a stale asynchronous summary switching a newer selection.
+*/
+async function navigateDurableConversation(session, expectedConversationId, targetId, context, options) {
+	return session.commit(async (tx) => {
+		const navigation = await tx.doc(DurableNavigationDoc);
+		if (navigation.activeConversationId !== expectedConversationId) throw new Error("The active conversation changed during navigation");
+		const next = targetId === null ? await tx.createConversation({ ownership: { kind: "ownerless" } }) : await tx.forkConversation(expectedConversationId, targetId, { ownership: { kind: "ownerless" } });
+		if (options?.summary) await tx.appendEntry(next.id, options.summary);
+		navigation.branches.push({
+			conversationId: next.id,
+			sourceConversationId: expectedConversationId,
+			targetId
+		});
+		navigation.activeConversationId = next.id;
+		return next.id;
+	}, context);
+}
+//#endregion
+export { DurableNavigationDoc, initializeDurableNavigation, navigateDurableConversation };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/durableNavigation/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/durableNavigation/index.ts"],"sourcesContent":["import type { Context } from '@earendil-works/chord';\nimport {\n  defineDoc,\n  type ConversationId,\n  type EntryDraft,\n  type EntryId,\n  type Session,\n} from '@earendil-works/pi-durable';\n\n/** External session identity is independent of the currently selected conversation. */\nexport const DurableNavigationDoc = defineDoc<{\n  activeConversationId: ConversationId | null;\n  branches: { conversationId: ConversationId; sourceConversationId: ConversationId; targetId: EntryId | null }[];\n}>({\n  kind: 'po.navigation',\n  version: 1,\n  scope: 'session',\n  initial: () => ({ activeConversationId: null, branches: [] }),\n});\n\n/** Select the initial conversation without overwriting a previously persisted selection. */\nexport async function initializeDurableNavigation(\n  session: Session,\n  conversationId: ConversationId,\n  context: Context,\n): Promise<ConversationId> {\n  return session.commit(async (tx) => {\n    if (!(await tx.conversation(conversationId))) throw new Error('Initial conversation does not exist');\n    const navigation = await tx.doc(DurableNavigationDoc);\n    navigation.activeConversationId ??= conversationId;\n    return navigation.activeConversationId;\n  }, context);\n}\n\n/**\n * Fork the selected history, retaining its abandoned tail. A head marker alone cannot rewind.\n * The caller must settle active work and prepare any summary before entering this transaction.\n * Expected selection guards against a stale asynchronous summary switching a newer selection.\n */\nexport async function navigateDurableConversation(\n  session: Session,\n  expectedConversationId: ConversationId,\n  targetId: EntryId | null,\n  context: Context,\n  options?: { summary?: EntryDraft },\n): Promise<ConversationId> {\n  return session.commit(async (tx) => {\n    const navigation = await tx.doc(DurableNavigationDoc);\n    if (navigation.activeConversationId !== expectedConversationId)\n      throw new Error('The active conversation changed during navigation');\n    const next =\n      targetId === null\n        ? await tx.createConversation({ ownership: { kind: 'ownerless' } })\n        : await tx.forkConversation(expectedConversationId, targetId, { ownership: { kind: 'ownerless' } });\n    if (options?.summary) await tx.appendEntry(next.id, options.summary);\n    navigation.branches.push({\n      conversationId: next.id,\n      sourceConversationId: expectedConversationId,\n      targetId,\n    });\n    navigation.activeConversationId = next.id;\n    return next.id;\n  }, context);\n}\n"],"mappings":";;;AAUA,MAAa,uBAAuB,UAGjC;CACD,MAAM;CACN,SAAS;CACT,OAAO;CACP,gBAAgB;EAAE,sBAAsB;EAAM,UAAU,CAAC;CAAE;AAC7D,CAAC;;AAGD,eAAsB,4BACpB,SACA,gBACA,SACyB;CACzB,OAAO,QAAQ,OAAO,OAAO,OAAO;EAClC,IAAI,CAAE,MAAM,GAAG,aAAa,cAAc,GAAI,MAAM,IAAI,MAAM,qCAAqC;EACnG,MAAM,aAAa,MAAM,GAAG,IAAI,oBAAoB;EACpD,WAAW,yBAAyB;EACpC,OAAO,WAAW;CACpB,GAAG,OAAO;AACZ;;;;;;AAOA,eAAsB,4BACpB,SACA,wBACA,UACA,SACA,SACyB;CACzB,OAAO,QAAQ,OAAO,OAAO,OAAO;EAClC,MAAM,aAAa,MAAM,GAAG,IAAI,oBAAoB;EACpD,IAAI,WAAW,yBAAyB,wBACtC,MAAM,IAAI,MAAM,mDAAmD;EACrE,MAAM,OACJ,aAAa,OACT,MAAM,GAAG,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,EAAE,CAAC,IAChE,MAAM,GAAG,iBAAiB,wBAAwB,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,EAAE,CAAC;EACtG,IAAI,SAAS,SAAS,MAAM,GAAG,YAAY,KAAK,IAAI,QAAQ,OAAO;EACnE,WAAW,SAAS,KAAK;GACvB,gBAAgB,KAAK;GACrB,sBAAsB;GACtB;EACF,CAAC;EACD,WAAW,uBAAuB,KAAK;EACvC,OAAO,KAAK;CACd,GAAG,OAAO;AACZ"}

package/dist/src/services/headlessClient/index.cjs

@@ -0,0 +1,126 @@
+const require_notification = require("../../schemas/notification.cjs");
+require("../../../notification.cjs");
+let node_crypto = require("node:crypto");
+//#region src/services/headlessClient/index.ts
+/** Explicit client interactions over the existing browser dialog protocol. */
+function createHeadlessClient(options) {
+	const pending = /* @__PURE__ */ new Map();
+	let disposed = false;
+	const advance = () => pending.values().next().value?.start();
+	return {
+		client: {
+			async notify(request) {
+				if (disposed) return;
+				const data = require_notification.createDoomNotificationEntryData(request);
+				if (!data) throw new Error("Invalid notification request");
+				try {
+					await options.appendCustomEntry(require_notification.DOOM_NOTIFICATION_ENTRY_TYPE, data);
+				} catch (error) {
+					if (disposed) return;
+					options.emitFrame({
+						type: "error",
+						code: "notification_undelivered",
+						error: `${data.body} (not saved to history: ${error instanceof Error ? error.message : String(error)})`
+					});
+				}
+			},
+			setStatus(source, text) {
+				if (disposed) throw new Error("Headless client is closed");
+				options.emitFrame({
+					type: "extension_ui_request",
+					method: "setStatus",
+					statusKey: source,
+					statusText: text
+				});
+			},
+			appendComposerText(text) {
+				if (disposed) throw new Error("Headless client is closed");
+				options.emitFrame({
+					type: "extension_ui_request",
+					method: "append_composer_text",
+					id: (0, node_crypto.randomUUID)(),
+					text
+				});
+			},
+			request(request, signal) {
+				if (disposed) return Promise.reject(/* @__PURE__ */ new Error("Headless client is closed"));
+				if (signal?.aborted) return Promise.resolve(void 0);
+				if (![
+					"confirm",
+					"select",
+					"input"
+				].includes(request.kind)) return Promise.reject(/* @__PURE__ */ new Error("Unsupported headless client request"));
+				const labels = request.options?.map((option) => option.label);
+				if (labels && new Set(labels).size !== labels.length) return Promise.reject(/* @__PURE__ */ new Error("Select option labels must be unique"));
+				const id = `headless-ui:${(0, node_crypto.randomUUID)()}`;
+				return new Promise((resolve, reject) => {
+					let started = false;
+					const finish = (outcome) => {
+						if (!pending.delete(id)) return;
+						signal?.removeEventListener("abort", abort);
+						try {
+							if (started) options.emitFrame({
+								type: "extension_ui_answered",
+								id
+							});
+							if ("error" in outcome) reject(outcome.error);
+							else resolve(outcome.value);
+						} catch (error) {
+							reject(error);
+						} finally {
+							advance();
+						}
+					};
+					const abort = () => finish({ value: void 0 });
+					pending.set(id, {
+						start() {
+							if (started || disposed) return;
+							started = true;
+							try {
+								options.emitFrame({
+									type: "extension_ui_request",
+									id,
+									method: request.kind === "input" && request.multiline ? "editor" : request.kind,
+									title: request.title,
+									message: request.message,
+									options: labels,
+									placeholder: request.message,
+									prefill: request.initialValue
+								});
+							} catch (error) {
+								finish({ error });
+							}
+						},
+						respond(frame) {
+							if (!started) return;
+							if (frame.cancelled === true) return finish({ value: void 0 });
+							if (request.kind === "confirm") {
+								if (typeof frame.confirmed === "boolean") finish({ value: frame.confirmed });
+							} else if (typeof frame.value === "string") {
+								const selected = request.options?.find((option) => option.label === frame.value);
+								finish({ value: selected?.value ?? frame.value });
+							}
+						},
+						close: () => finish({ error: /* @__PURE__ */ new Error("Headless client is closed") })
+					});
+					signal?.addEventListener("abort", abort, { once: true });
+					advance();
+				});
+			}
+		},
+		receive(frame) {
+			if (frame.type !== "extension_ui_response") return false;
+			if (typeof frame.id === "string") pending.get(frame.id)?.respond(frame);
+			return true;
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			for (const request of pending.values()) request.close();
+		}
+	};
+}
+//#endregion
+exports.createHeadlessClient = createHeadlessClient;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/headlessClient/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["createDoomNotificationEntryData","DOOM_NOTIFICATION_ENTRY_TYPE","randomUUID"],"sources":["../../../../src/services/headlessClient/index.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport { createDoomNotificationEntryData, DOOM_NOTIFICATION_ENTRY_TYPE } from '../../exports/notification';\nimport type {\n  HeadlessClientBridge,\n  HeadlessClientOptions,\n  PendingClientRequest,\n} from '../../types/server/headlessClient';\n\n/** Explicit client interactions over the existing browser dialog protocol. */\nexport function createHeadlessClient(options: HeadlessClientOptions): HeadlessClientBridge {\n  const pending = new Map<string, PendingClientRequest>();\n  let disposed = false;\n  const advance = (): void => pending.values().next().value?.start();\n\n  return {\n    client: {\n      async notify(request) {\n        // Detached callbacks can outlive their session. A closed client has no recipient.\n        if (disposed) return;\n        const data = createDoomNotificationEntryData(request);\n        if (!data) throw new Error('Invalid notification request');\n        try {\n          await options.appendCustomEntry(DOOM_NOTIFICATION_ENTRY_TYPE, data);\n        } catch (error) {\n          if (disposed) return;\n          // Callers fire notify without awaiting, often to report a journal failure. A rejection here\n          // would crash the session server, so a refused append still reaches the browser live.\n          options.emitFrame({\n            type: 'error',\n            code: 'notification_undelivered',\n            error: `${data.body} (not saved to history: ${error instanceof Error ? error.message : String(error)})`,\n          });\n        }\n      },\n      setStatus(source, text) {\n        if (disposed) throw new Error('Headless client is closed');\n        options.emitFrame({ type: 'extension_ui_request', method: 'setStatus', statusKey: source, statusText: text });\n      },\n      appendComposerText(text) {\n        if (disposed) throw new Error('Headless client is closed');\n        options.emitFrame({ type: 'extension_ui_request', method: 'append_composer_text', id: randomUUID(), text });\n      },\n      request(request, signal) {\n        if (disposed) return Promise.reject(new Error('Headless client is closed'));\n        if (signal?.aborted) return Promise.resolve(undefined);\n        if (!['confirm', 'select', 'input'].includes(request.kind)) {\n          return Promise.reject(new Error('Unsupported headless client request'));\n        }\n        const labels = request.options?.map((option) => option.label);\n        if (labels && new Set(labels).size !== labels.length) {\n          return Promise.reject(new Error('Select option labels must be unique'));\n        }\n        const id = `headless-ui:${randomUUID()}`;\n        return new Promise((resolve, reject) => {\n          let started = false;\n          const finish = (outcome: { value: unknown } | { error: unknown }): void => {\n            if (!pending.delete(id)) return;\n            signal?.removeEventListener('abort', abort);\n            try {\n              if (started) options.emitFrame({ type: 'extension_ui_answered', id });\n              if ('error' in outcome) reject(outcome.error);\n              else resolve(outcome.value);\n            } catch (error) {\n              reject(error);\n            } finally {\n              advance();\n            }\n          };\n          const abort = (): void => finish({ value: undefined });\n          pending.set(id, {\n            start() {\n              if (started || disposed) return;\n              started = true;\n              try {\n                options.emitFrame({\n                  type: 'extension_ui_request',\n                  id,\n                  method: request.kind === 'input' && request.multiline ? 'editor' : request.kind,\n                  title: request.title,\n                  message: request.message,\n                  options: labels,\n                  placeholder: request.message,\n                  prefill: request.initialValue,\n                });\n              } catch (error) {\n                finish({ error });\n              }\n            },\n            respond(frame) {\n              if (!started) return;\n              if (frame.cancelled === true) return finish({ value: undefined });\n              if (request.kind === 'confirm') {\n                if (typeof frame.confirmed === 'boolean') finish({ value: frame.confirmed });\n              } else if (typeof frame.value === 'string') {\n                // Rich questionnaire clients return an encoded whole-answer envelope here.\n                const selected = request.options?.find((option) => option.label === frame.value);\n                finish({ value: selected?.value ?? frame.value });\n              }\n            },\n            close: () => finish({ error: new Error('Headless client is closed') }),\n          });\n          signal?.addEventListener('abort', abort, { once: true });\n          advance();\n        });\n      },\n    },\n    receive(frame) {\n      if (frame.type !== 'extension_ui_response') return false;\n      if (typeof frame.id === 'string') pending.get(frame.id)?.respond(frame);\n      return true;\n    },\n    dispose() {\n      if (disposed) return;\n      disposed = true;\n      for (const request of pending.values()) request.close();\n    },\n  };\n}\n"],"mappings":"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"}