Phosra Developer SDK

@phosra/sdk-dev is the TypeScript SDK for developers building on the Phosra platform. It has two distinct, clearly-named halves: a management client for the Phosra control-plane REST API, and an OCSS protocol surface that re-exports @openchildsafety/ocss — the open standard's reference implementation — verbatim.

Phosra follows OCSS; it does not own it

Phosra is an accredited provider on the Open Child Safety Specification (OCSS). The relationship is the same as Yubico shipping a FIDO2-conformant authentication key: Yubico implements FIDO2; the FIDO Alliance owns the standard. Phosra implements OCSS; the OCSS stewardship body owns the standard.

The consequence for this SDK: the protocol signing and verification primitives (@phosra/sdk-dev/protocol) are not Phosra code — they are @openchildsafety/ocss, the vendor-neutral OCSS library, re-exported without modification. Phosra adds zero cryptographic logic to the protocol surface. If you later integrate a different OCSS-conformant provider, the /protocol subpath is identical across all of them.

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.

Working name: @phosra/sdk-dev. The final public package name is a publish-time decision and may change before the 1.0 release.

Two halves

Half 1 — Management: @phosra/sdk-dev

import { createOrg, createApiKey, registerAdvisor } from "@phosra/sdk-dev";

The root import is the generated control-plane client, produced from the Phosra OpenAPI spec by hey-api. It covers:

• Organizations — create, read, update, delete developer orgs; list members.
• API keys — provision, revoke, and rotate phosra_-prefixed keys.
• Usage — hourly request rollups per org.
• Advisor agents — register, consult, and declare payload keys for OCSS federation.
• MCP tokens — mint and revoke Model Context Protocol authentication tokens.

The root import is intentionally crypto-free: no signing primitives are accessible here. Management operations use standard HTTP Bearer authentication with a phosra_ API key.

Half 2 — OCSS protocol: @phosra/sdk-dev/protocol

import { signReceipt, verifyReceipt }  from "@phosra/sdk-dev/protocol";
import { seal, open }                   from "@phosra/sdk-dev/protocol/envelope";

The /protocol subpath is @openchildsafety/ocss re-exported verbatim — the open standard's reference TypeScript implementation. Phosra adds nothing here. This surface covers:

• Receipt signing and verification — sign and verify OCSS write receipts against the Trust Framework.
• Sealed envelopes — router-blind sealed payloads (the harm_context lane).
• Vocabulary, canon, and checksums — OCSS rule vocabulary, canonical JSON serialization, family hash derivation.
• Trust list — resolve and verify the OCSS Trust List.

Quick start

Configure the management client

import { client } from "@phosra/sdk-dev";
 
client.setConfig({
  baseUrl: "https://prodapi.phosra.com/api/v1",
  headers: {
    Authorization: `Bearer ${process.env.PHOSRA_API_KEY}`,
  },
});

Create a developer organization

import { createOrg } from "@phosra/sdk-dev";
 
const { data, error } = await createOrg({
  body: {
    name: "Acme Corp",
    description: "Acme's OCSS integration",
    website_url: "https://acme.example.com",
  },
  headers: {
    Authorization: `Bearer ${process.env.PHOSRA_API_KEY}`,
  },
});
 
if (error) {
  // error.message, error.code, error.error (HTTP status text)
  throw new Error(`createOrg failed: ${error.message}`);
}
 
console.log("Created org:", data.id, data.slug);

PHOSRA_API_KEY is a developer-tier key with the phosra_ prefix, issued to your developer account.

Sign an OCSS receipt (protocol half)

import { signReceipt, verifyReceipt } from "@phosra/sdk-dev/protocol";
 
// Sign
const receipt = await signReceipt(body, mySigningKey);
 
// Verify against the published Trust List
const result = await verifyReceipt(receipt, trustListResolver);

Management operations reference

All operations are generated functions that accept an Options<…Data> object and return a RequestResult (a Promise resolving to { data, error }). The generic ThrowOnError parameter controls whether errors throw (default: false — check error in the result).

TypeScript types

All types are generated from the Phosra OpenAPI spec and re-exported from the root import:

import type {
  DeveloperOrg,
  DeveloperApiKey,
  DeveloperApiKeyWithSecret,   // includes raw `key` — returned once at create/regenerate
  AdvisorRegistration,
  McpToken,
  CreatedMcpToken,             // includes raw `plain` token — returned once
  DeveloperUsage,
} from "@phosra/sdk-dev";

Base URLs

The generated client defaults to the production URL. Override with client.setConfig({ baseUrl: "..." }).

Subpath exports

The management root (@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.

Further reading

• OCSS specification — the vendor-neutral standard this SDK conforms to
• @openchildsafety/ocss package — the open OCSS TypeScript library (re-exported as /protocol)
• Phosra API reference — full REST endpoint documentation
• MCP Server — Model Context Protocol integration for AI agents