PhIP — Physical Information Protocol

A federated protocol for formatting, addressing, querying, and exchanging information about physical objects across organizational and system boundaries — at any point during design, manufacturing, deployment, or end-of-life.

PhIP is to physical objects what HTTP/DNS was to documents: a universal addressing and exchange protocol. It is not an ERP, MES, file format, communication bus, or blockchain.

Status: 0.1.0-draft. The protocol is implementable but not stable — minor versions may introduce breaking changes until the spec hits 1.0. See VERSIONING.md.

Quick links

Document	What it is
TUTORIAL.md	15-minute end-to-end tour: what PhIP is, the ecosystem, a working stack
spec/phip-core.md	The full normative specification
spec/CHANGELOG.md	What changed in each revision
schemas/	JSON Schemas: core object, attribute namespaces, capability tokens, /meta, bundle manifest
tests/conformance/	Black-box HTTP conformance suite — npm install -g @phip/conformance
tests/vectors/	Language-agnostic test fixtures: JCS, Ed25519, hash chains, lifecycle, tokens, bundles
phip-server	Reference server implementation (Python + FastAPI, Docker Compose for one-command spinup) — runs the protocol end-to-end
phip-cli	phip command-line tool: identity + remote management, server integration, protocol plumbing
phip-py	Python client library — URI resolution, event signing, chain verification, federation
IMPLEMENTATIONS.md	Registry of known implementations and conformance status
CONTRIBUTING.md	How to file issues and submit PRs
VERSIONING.md	Spec, schema, and library versioning rules
LIABILITY.md	How PhIP claims relate to contracts, evidence, and statutory records

What problem PhIP solves

Cross-organizational provenance for physical things. Today, when a part moves between Apple → Foxconn → Quanta → a datacenter operator → a recycler, every handoff loses or rewrites information. There is no universal way to say "this object's history is at this URL, signed by these parties, verifiable end-to-end" — so each organization stores its own incompatible record, and provenance evaporates at every boundary.

PhIP defines:

• Identity — a federated URI scheme (phip://{authority}/{namespace}/{local-id}) resolvable via a well-known HTTPS endpoint
• Object model — four required fields (phip_id, object_type, state, history) shared by every PhIP object
• Schema namespaces — extensible typed attributes (phip:mechanical, phip:datacenter, phip:software, phip:compliance, phip:geo, phip:access)
• Lifecycle state machine — enforced transitions across two tracks: manufacturing (concept → design → … → disposed) and operational (planned → active → inactive → archived)
• Trust model — Ed25519-signed events, hash-chained append-only history, capability tokens for cross-org writes, foreign-authority key resolution for cross-org token verification
• Federation primitives — authority delegation (sub-namespace hand-off), authority transfer (acquisition / domain death), mirror snapshots (archival)

All data crosses the wire as canonical JSON (RFC 8785), all events carry verifiable signatures, all writes go through an enforced state machine.

Architecture in five layers

Layer	What it does
5. Trust	Ed25519 event signing, hash-chained history, capability tokens, mTLS / RFC 9421 caller authentication
4. Lifecycle	State machine; enforced transitions; terminal states
3. Schema namespaces	Domain-specific typed attributes (phip:datacenter, phip:mechanical, …)
2. Object model	Required fields; event log structure; history projection
1. Identity	URI scheme, resolver discovery, redirect/transfer/delegation rules

Protocol operations: CREATE, GET, PUSH, QUERY, history, batch_create, batch_push, meta — all over HTTPS.

Try it

Run the reference resolver

cd reference
npm install
PHIP_AUTHORITY=test.local PHIP_PORT=8080 npm start

In another terminal, prove it works:

cd tests/conformance
node run.js http://127.0.0.1:8080 --authority test.local
# 76 passed, 0 failed

Validate any other PhIP server

If you've built a PhIP server in another language, install the conformance suite globally and probe your server:

npm install -g @phip/conformance
phip-conformance http://my-resolver.example --authority my-authority.example

Read the test vectors

The fixtures in tests/vectors/ are language-agnostic. Any client library that produces byte-identical output on these inputs is wire-compatible with the reference. Implementing PhIP in a new language? Start there.

Implementations

See IMPLEMENTATIONS.md for the current registry. To add yours, open a PR after passing the vectors and (for servers) the conformance suite.

Planned first-party implementations under github.com/mfgs-us:

• phip-py — Python client library
• phip-rs — Rust client library (no_std-friendly for embedded)
• phip-server — production server (Go, single binary)
• phip-cli — operator CLI (Go)
• phip-js — JavaScript / TypeScript client library
• phip-datacenter — vertical example application

The phip repo (this one) holds the spec, schemas, conformance suite, test vectors, and a minimal reference. Everything else lives in its own repo.

Repository layout

phip/
├── spec/              # The specification — phip-core.md is normative
├── schemas/           # JSON Schemas (object, namespaces, tokens, meta, bundle)
├── tests/
│   ├── vectors/       # Language-agnostic fixtures
│   └── conformance/   # HTTP conformance suite (also @phip/conformance)
├── README.md
├── CONTRIBUTING.md
├── VERSIONING.md
├── IMPLEMENTATIONS.md
├── LIABILITY.md
└── LICENSE

The reference server lives in its own repo at mfgs-us/phip-server (Python + FastAPI + Postgres/SQLite, Docker Compose for one-command spinup). It runs the protocol end-to-end and is what implementers should check their work against. The earlier minimal Node reference was retired in favor of phip-server so the protocol primitives (canonicalization, signing, chain validation) have a single language-shared implementation via phip-py.

Contributing

See CONTRIBUTING.md. The PR checklist requires passing:

• Reference-server smoke (run via phip-server)
• cd tests && npm run self-check — language-agnostic vectors (189 assertions)
• cd tests/conformance && node run.js <url> — HTTP conformance suite against a running resolver (76 assertions plus federation §20)

Spec changes should reference an Appendix A entry. Editorial changes can skip the issue step.

License

Apache 2.0. See LICENSE.

Repository

github.com/mfgs-us/phip