OCSS Protocol SDK

@phosra/sdk-dev/protocol is @openchildsafety/ocss re-exported verbatim. Phosra adds zero cryptographic logic to this subpath. If you later integrate a different OCSS-conformant provider, this import is identical across all of them.

The management/protocol boundary

@phosra/sdk-dev has two clearly-named halves. Understanding the split matters because it is the ownership-boundary made legible in code:

The root import (@phosra/sdk-dev) does not re-export the protocol surface. This is intentional: it keeps crypto off the management import and makes the OCSS/Phosra boundary legible to tree-shakers and to readers.

See Phosra Developer SDK for the full SDK reference including the management half.

What the protocol surface covers

The /protocol subpath is the OCSS reference TypeScript library. It covers the full Trust Framework verification surface:

• Receipt signing and verification — sign OCSS write receipts with an Ed25519 signing key; verify receipts against the Trust List.
• Sealed envelopes — create and open the two-layer OCSS envelope (the harm_context router-blind lane).
• Rule vocabulary and canon — the 115-category rule vocabulary as typed identifiers; canonical JSON serialization for deterministic hashing.
• Family hash derivation — compute the family-scoped hash that appears in receipts and attestation exports.
• Trust List resolution — fetch and verify the Trust List; resolve a signing party's key from it.

Installation

npm install @phosra/sdk-dev @openchildsafety/ocss

@openchildsafety/ocss is a peer dependency — the open OCSS library. Installing it separately keeps the OCSS version pinnable independently of the Phosra management client version.

Usage

Sign a write receipt

import { signReceipt } from "@phosra/sdk-dev/protocol";
 
const receipt = await signReceipt(
  {
    rule_category: "addictive_pattern_block",
    decision: "block",
    writer: "did:ocss:your-org",
    standing: "consent:att-mia-addictive-2026",
  },
  myEd25519SigningKey
);

Verify a receipt against the Trust List

import { verifyReceipt, makeTrustListResolver } from "@phosra/sdk-dev/protocol";
 
const trustListResolver = makeTrustListResolver(
  "https://prodapi.phosra.com/.well-known/ocss/trust-list",
  rootPublicKeyX // base64url-encoded X coordinate of the root Ed25519 key
);
 
const result = await verifyReceipt(receipt, trustListResolver);
 
if (!result.ok) {
  console.error("Verification failed:", result.error);
}

Sealed envelopes (router-blind lane)

import { seal, open } from "@phosra/sdk-dev/protocol/envelope";
 
// Sender: seal a payload to the recipient's declared payload key
const sealed = await seal(innerPayload, recipientPayloadKey);
 
// Recipient: open the sealed payload
const plaintext = await open(sealed, myPayloadPrivateKey);

The router handles the sealed blob as an opaque byte string — it reads only the outer-layer headers needed for routing and never calls open. This is cryptographic enforcement of the router-blind invariant (OCSS §3A.3), not a policy.

Resolve the Trust List

import { fetchTrustList, verifyTrustListSignature } from "@phosra/sdk-dev/protocol";
 
const raw = await fetchTrustList("https://prodapi.phosra.com/.well-known/ocss/trust-list");
const trustList = await verifyTrustListSignature(raw, rootPublicKeyX);
 
// Look up an accredited party
const entry = trustList.entries.find(e => e.did === "did:ocss:your-org");

Importing directly from @openchildsafety/ocss

Because /protocol is a verbatim re-export, you can import directly from @openchildsafety/ocss if you prefer — the symbols are identical:

// These are equivalent:
import { signReceipt } from "@phosra/sdk-dev/protocol";
import { signReceipt } from "@openchildsafety/ocss";

Importing via /protocol is recommended when you want the dependency footprint of @phosra/sdk-dev to cover both halves in package.json. Import directly from @openchildsafety/ocss if you are not using the Phosra management surface at all.

Subpath exports

Further reading

• Phosra Developer SDK — the full SDK reference, including the management half
• Trust Framework — the Trust List and signing model the protocol surface implements
• OCSS specification — normative text for signed verbs, envelopes, and the §9.4 attestation export