A full-featured download manager.
// src/shared/protocol/bridge.ts
import { z } from 'zod'
/** Browser families the bridge pairs with. Canonical runtime contract. */
export const BrowserSchema = z.enum(['chromium', 'firefox', 'safari'])
export type Browser = z.infer<typeof BrowserSchema>
export const EXTENSION_ORIGIN_SCHEMES: Readonly<Record<Browser, string>> =
Object.freeze({
chromium: 'chrome-extension',
firefox: 'moz-extension',
safari: 'safari-web-extension',
})
export function isBridgeBrowser(value: unknown): value is Browser {
return BrowserSchema.safeParse(value).success
}
/** Safari's lowercase UUID Origin identifies an installation, not a signed bundle. */
export function isSafariExtensionOrigin(origin: string): boolean {
return /^safari-web-extension:\/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(
origin
)
}
/** Extension-wide trust/revocation key. Active connections use the full MBP1
* credential principal, including its installation ID, instead. */
export function makeSessionKey(browser: Browser, extensionId: string): string {
return `${browser}:${extensionId}`
}
/**
* Client identity primitive for the bridge. Generalizes the historically
* browser-coupled `(browser, extensionId)` pair so non-extension clients are
* first-class. The `kind` discriminant keeps the extension path byte-identical
* while admitting a `cli` principal (Spec 3) for the unary `POST /mdxp`
* surface; later specs widen it further (e.g. persisted device-code clients).
*/
export type ClientIdentity =
| {
readonly kind: 'extension'
readonly browser: Browser
readonly extensionId: string
}
| { readonly kind: 'cli'; readonly id: string }
/** Group identity key for extension trust/revocation and CLI authorization. */
export function clientKey(identity: ClientIdentity): string {
switch (identity.kind) {
case 'extension':
return makeSessionKey(identity.browser, identity.extensionId)
case 'cli':
return `cli:${identity.id}`
}
}
export const BridgeCommands = {
RevokePair: 'bridge:revokePair',
AddTrusted: 'bridge:addTrusted',
RemoveTrusted: 'bridge:removeTrusted',
ResolvePair: 'bridge:resolvePair',
ClaimExtensionPair: 'bridge:claimExtensionPair',
} as const
export const BridgeQueries = {
ListPaired: 'bridge:listPaired',
ListTrusted: 'bridge:listTrusted',
ProbeUrl: 'bridge:probeUrl',
ResolveUrl: 'bridge:resolveUrl',
CancelResolveUrl: 'bridge:cancelResolveUrl',
ListPendingPairRequests: 'bridge:listPendingPairRequests',
GetStatus: 'bridge:getStatus',
} as const
export const BridgeEvents = {
PairRequested: 'bridge:pairRequested',
Paired: 'bridge:paired',
Revoked: 'bridge:revoked',
ExtensionSessionsChanged: 'bridge:extensionSessionsChanged',
Error: 'bridge:error',
/** A pending request reached a non-TTL terminal outcome. */
PairRequestSettled: 'bridge:pairRequestSettled',
/** A pending pair request lapsed past its TTL without a decision. */
PairRequestExpired: 'bridge:pairRequestExpired',
} as const
export type BridgeCommand = (typeof BridgeCommands)[keyof typeof BridgeCommands]
export type BridgeQuery = (typeof BridgeQueries)[keyof typeof BridgeQueries]
export type BridgeEvent = (typeof BridgeEvents)[keyof typeof BridgeEvents]
export interface ExtensionInstallationInfo {
/** Opaque non-secret installation key, stable across reconnects. */
id: string
pairedAt: number
connected: boolean
}
/**
* Renderer-facing paired-client DTO (the token is never exposed). Discriminated
* on `kind`, mirroring {@link ClientIdentity}: an `extension` carries its
* `browser`; a `cli` (device-code paired, Spec 7b) does not. `id` is the
* extension id or the cli id respectively.
*/
export type PairedClientInfo =
| {
kind: 'extension'
id: string
browser: Browser
name: string
identityTrust: IdentityTriState
status: 'ready' | 'cleanup-pending'
/** Optional for compatibility with older paired-list providers. */
installations?: ExtensionInstallationInfo[]
pairedAt: number
lastActiveAt: number | null
}
| {
kind: 'cli'
id: string
name: string
pairedAt: number
lastActiveAt: number | null
}
export interface TrustedExtensionInfo {
id: string
browser: Browser
source: 'builtin' | 'user-added' | 'imported'
label?: string
addedAt: number
}
/**
* Renderer-facing snapshot of the bridge's current port policy (§4), read by
* {@link BridgeQueries.GetStatus}. Lets the settings UI surface a degraded
* (ephemeral-port) bridge as informational, not an error — `endpoint.json`
* remains the authoritative discovery source, and the CLI and native
* messaging host are unaffected by this query existing or not.
*/
export interface BridgeStatusInfo {
/** The port actually bound (`BridgeRuntime.port`). `null` only if a future
* caller reads this before a port is bound; today the query handler is
* installed after binding, so it always returns a real number. */
port: number | null
/** True once every candidate in the §4 port range (or the pinned
* `fixedPort`) was taken and the bridge fell back to an ephemeral port —
* extension port-probing can no longer find it. */
degraded: boolean
/** Whether the durable Extension credential-to-management projection is
* healthy. `degraded` means Extension access has been gated for this run and
* the paired list must not be interpreted as complete. */
extensionPairingHealth: 'ready' | 'degraded'
/** The persisted port policy (`BridgeSettings.fixedPort`) that produced
* `port`/`degraded`. */
fixedPort: 'auto' | number
/** The persisted §4.1 discovery routing hint (`BridgeSettings.instanceId`).
* A routing hint only — never a security signal. */
instanceId: string
}
/**
* The §5/§9.2 tri-state proof level for an extension's identity. A literal
* copy of core's `IdentityTriState` (`src/core/bridge/credential-store.ts`) —
* duplicated deliberately because the renderer must not import `@core/`.
* `src/main/bridge/pairing-dialog-controller.ts` asserts the two stay
* assignable both ways at compile time, so a future widening of either union
* fails `tsc` instead of silently diverging.
*/
export type IdentityTriState =
| 'official'
| 'attested-non-official'
| 'unverified'
/**
* Renderer-facing pairing-approval prompt payload. Discriminated on `kind`:
* an `extension` pairing (the browser `/pair` handshake) vs a `cli` device-code
* pairing (Spec 7b). The approval toast branches on `kind` — a `cli` request
* carries the human-verifiable `userCode` instead of a browser/extensionId.
*
* Under MBP1 (§5) no self-reported extension name/version is ever displayed:
* `extensionId` is the pairHello `claimedExtensionId` — proven whenever
* `identity !== 'unverified'`, claimed-only when `unverified` — and `code` is
* the §7.1 pairing code the user types into the extension to actually
* authorize it. There is no `decision` to make here any more: approval is
* proven by typing the code, not by a click in this dialog.
*/
export interface ExtensionPairRequestDetails {
pairingNonce: string
extensionId: string
browser: Browser
identity: IdentityTriState
verifiedOrigin?: string
originHost?: string
claimedExtensionId?: string
attestationClass?: IdentityTriState
publicAuthority?: string
}
export type ExtensionCodeRequest = ExtensionPairRequestDetails & {
kind: 'extension'
/** PAKE password: render verbatim, never log or persist. */
code: string
}
/** A NAS operator must deliberately claim this request before receiving a code.
* This variant is safe to publish to the shared administrator inbox. */
export type ExtensionClaimRequest = ExtensionPairRequestDetails & {
kind: 'extension-claim'
createdAt: number
expiresAt: number
}
export type PairRequestPayload =
| ExtensionCodeRequest
| ExtensionClaimRequest
| {
kind: 'cli'
requestId: string
userCode: string
clientName: string
clientVersion: string
}
/**
* Renderer → main/server decision for a pairing prompt. Mirrors
* {@link PairRequestPayload}'s discriminant: a `cli` decision approves/denies
* a device-code request by its `requestId`. An `extension` request has
* shrunk to a pure dismiss — under MBP1 the desktop dialog only DISPLAYS the
* code (§7.1); there is no Allow/Deny affordance, since approval is proven by
* typing the code into the extension, not by a click here.
*/
export type ResolvePairParams =
| {
kind: 'extension'
pairingNonce: string
extensionId: string
browser: Browser
}
| {
kind: 'cli'
requestId: string
decision: 'allow' | 'deny'
}
/**
* Renderer-safe DTO for a pending pairing request, shown in the approval
* inbox. Discriminated on `kind`, mirroring {@link PairRequestPayload}: a
* `cli` device-code request (token-free by construction, mirrors
* {@link getPending}'s projection; `deviceId` — identity-keying material — is
* deliberately excluded) vs an `extension` `/pair` handshake still awaiting
* the code being typed into the extension. Both add `createdAt`/`expiresAt`
* for ordering + the TTL countdown.
*/
export type PendingPairRequestInfo =
| {
kind: 'cli'
requestId: string
userCode: string
clientName: string
clientVersion: string
createdAt: number
expiresAt: number
}
| (ExtensionCodeRequest & { createdAt: number; expiresAt: number })
| ExtensionClaimRequest
/**
* Stable identity for prompt isolation and lifecycle routing. Mirrors the two
* kinds a pending request can have: `cli:${requestId}` for a device-code
* request (namespaced under `cli:`, matching {@link clientKey}'s cli prefix,
* so the two spaces cannot collide) and `${browser}:${extensionId}:${pairingNonce}`
* for an extension request — byte-identical to
* {@link PairingDialogController}'s existing map key.
*/
export function pairRequestKey(
info:
| Pick<
Extract<PendingPairRequestInfo, { kind: 'cli' }>,
'kind' | 'requestId'
>
| Pick<
Extract<
PendingPairRequestInfo,
{ kind: 'extension' | 'extension-claim' }
>,
'kind' | 'pairingNonce' | 'extensionId' | 'browser'
>
): string {
return info.kind === 'cli'
? `cli:${info.requestId}`
: `${info.browser}:${info.extensionId}:${info.pairingNonce}`
}
/** Payload for {@link BridgeEvents.PairRequestSettled}: a pending pair
* request (identified by {@link pairRequestKey}) reached a non-TTL terminal
* outcome. `aborted` is transport/session teardown, never operator denial. */
export interface PairRequestSettledPayload {
key: string
outcome: 'allowed' | 'denied' | 'aborted'
}
/** Payload for {@link BridgeEvents.PairRequestExpired}: a pending pair
* request (identified by {@link pairRequestKey}) lapsed past its TTL without
* a decision. */
export interface PairRequestExpiredPayload {
key: string
}
/**
* Result of a cli `ResolvePair`. A discriminated RETURN VALUE rather than a
* thrown error: a thrown MDXP error loses its `code`/`data.appCode` over the
* web `/rpc` transport (it becomes a generic 500 message), whereas a return
* value round-trips intact over both Electron IPC and HTTP. `'unavailable'`
* means the request was no longer pending (expired / denied-elsewhere /
* already approved).
*/
export type ResolvePairResult =
| { ok: true }
| { ok: false; reason: 'unavailable' }
/** appCodes attached to device-code pairing errors (DeviceCodeService). Shared
* so the per-shell ResolvePair handlers match the same string the service
* throws — never re-type the literal. */
export const PairAppCodes = {
Unavailable: 'pair.request.unavailable',
RateLimited: 'pair.request.rateLimited',
} as const