@schwaizer/ocp-protocol
v0.9.0
Published
OCP — Open Companion Protocol. Core + profile message contracts (Zod), .well-known schema, and conformance test vectors.
Readme
@schwaizer/ocp-protocol
OCP — Open Companion Protocol. An open standard for answering a question about a page from a device that is not the one showing the page: a QR-paired phone carrying the microphone and, optionally, the model — for a kiosk, a TV, a shared terminal, or any screen whose own microphone is not the one to use.
For the same-device case a browser-native agent needs none of this; the root README says so and says why this protocol exists anyway.
This package is the standard:
src/— the authoritative message contracts (Zod): envelope, errors, sessions, context, turns, tools, confirms, pairing,.well-knowndiscovery.SPEC/— normative prose (RFC-2119):core.md,companion.md,companion-provider.md,embed.md,provider.md,mcp.md.retired/sealing.mdis the sealing profile — retired in 0.6.0, never functional — under a banner stating what happened and what replaced it.vectors/— golden conformance vectors. An implementation that rejects a "valid" vector (or accepts a "reject" one) is non-conformant; changing that boundary is a major-version protocol change.
Design pillars: four strictly-separated roles (Surface / Hub / Companion / Provider), Hub-brokered trust, delegated QR pairing with proof-of-possession tokens and mandatory human approval, additive-only evolution with ignore-unknown semantics.
Companion contracts include silent token refresh (session.refresh /
session.refreshed) and negotiated answer generation — capabilities.answer,
answerMode, answeredBy — for the Companion that brings its own model
(SPEC/companion-provider.md); the Embed profile adds the host↔iframe
postMessage contract (embed.ts, consumed by @schwaizer/ocp-embed).
answeredBy is disclosure, not routing (SPEC/core.md §5.2). A session whose
Hub relays to a phone that answers and a session whose Hub answers itself are
indistinguishable on the wire without it, and they have opposite privacy
properties: in hub mode the question reaches the Hub operator and whatever
provider it runs. Both are conformant deployments of this standard.
The sealing profile is retired — it never worked end to end, in any
implementation — and its wire contract stays registered in 1.0 for parsing
only, because withdrawing a registered message type is a major-version change:
sealed, sealMode, pair.reveal, SEAL_REQUIRED (sealing.ts), and the
byte-level seal-contract.ts — HKDF labels, AAD layout, nonce rule, SAS
reduction — with known-answer vectors in vectors/sealing.json. Nothing in
this repository negotiates any of it. The design was a relay that routes
without reading: keys agreed half by camera and half through the Hub, compared
as six digits on the approval screen pairing already requires.
SPEC/retired/sealing.md has the reason it never worked on its first page, and
its §1 states what sealing did not protect even as designed, including the Hub
serving the widget's own JavaScript; that limit is part of the specification,
not a footnote to it.
Status: v1.0-draft (Core + Companion shipped; Embed backbone shipped). License: Apache-2.0 (code) / CC-BY (spec).
