OCSS Protocol SDK

npm install @openchildsafety/ocss

import { signReceipt } from "@openchildsafety/ocss";

// signReceipt(type, body, key, now, entropy) — the SigningKey is
// { keyId: "did:ocss:<slug>#<kid>", sign(msg): Uint8Array }. A "write" body
// (WriteBody) requires all six fields below — writer_ref / standing_ref, not
// writer / standing, and rule_id + applied_at are required, not optional.
const receipt = signReceipt(
  "write",
  {
    rule_id: "f3a1c9e0-2b4d-4e6f-9a1b-8c7d6e5f4a3b",
    rule_category: "addictive_pattern_block",
    decision: "block",
    writer_ref: "did:ocss:your-org",
    standing_ref: "consent:att-mia-addictive-2026",
    applied_at: new Date().toISOString(), // RFC3339 UTC
  },
  mySigningKey,                 // { keyId, sign }
  new Date(),
  crypto.getRandomValues(new Uint8Array(16)),
);

import { verifyDocument, fromVerifiedDocument, verifyReceipt } from "@openchildsafety/ocss";

// 1. Root-verify the fetched Trust List (see "Verify a signed document to root" below),
//    then build a resolver over the verified document.
const trustList = verifyDocument(signedTrustList, rootPublicKeyX);
const resolver  = fromVerifiedDocument(trustList);

// 2. verifyReceipt is synchronous and THROWS SignatureInvalidError / UnknownKeyError
//    on failure (it does not return an { ok } result). The second arg is a KeyResolver
//    `(keyId) => Ed25519PublicKey` — pass the resolver's bound signingKey.
try {
  verifyReceipt(receipt, resolver.signingKey.bind(resolver));
} catch (err) {
  console.error("Verification failed:", (err as Error).message);
}

import { seal, open } from "@openchildsafety/ocss/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);

import { verifyDocument } from "@openchildsafety/ocss";

const resp = await fetch(
  "https://phosra-api-sandbox-production.up.railway.app/.well-known/ocss/trust-list"
);
const raw = await resp.json();

// verifyDocument root-verifies the Ed25519 signature and returns the parsed
// TrustListDocument (throws TrustListVerifyError on failure).
const trustList = verifyDocument(raw, rootPublicKeyX);

// Look up an accredited party
const entry = trustList.entries.find(e => e.did === "did:ocss:your-org");

import { verifyDocument, fromVerifiedDocument } from "@openchildsafety/ocss";

// 1. Fetch the signed trust list from the census
const resp = await fetch(
  "https://phosra-api-sandbox-production.up.railway.app/.well-known/ocss/trust-list"
);
const signed = await resp.json();

// 2. Verify the Ed25519 root signature — throws TrustListVerifyError if it fails
//    Prod sandbox root X (base64url, full key):
const trustList = verifyDocument(
  signed,
  "CMHWy3vUAiEcYDdE_bDvkRuEqwxkklS0tV-TYHJTlWU"
);

// 3. Build a key resolver for subsequent receipt / profile verification
const resolver = fromVerifiedDocument(trustList);
// resolver.signingKey("did:ocss:<slug>#<kid>") → Ed25519PublicKey (Uint8Array).
// It THROWS TrustListResolveError on an unknown/expired/revoked key — it does
// NOT return null. Pass resolver.signingKey.bind(resolver) as the KeyResolver
// to verifyReceipt.

// For the staging sandbox, use root X:
// "jDWZfB70DM8B3ZnPG8FQ0tnanqLgwJX4ZMr_E1Ugv3w"

// Once @phosra/sdk-dev ships, these will be equivalent (verbatim re-export):
import { signReceipt } from "@phosra/sdk-dev/protocol";  // planned wrapper
import { signReceipt } from "@openchildsafety/ocss";     // available today