@phosra/connect — PhosraConnect - Phosra Developer Docs

@phosra/connect is the parent-facing connect surface — a calm, branded, in-app modal that never navigates away, shows exactly which child and which rules are being granted, and ends on an explicit success. It is the Plaid Link of OCSS: the same recognizable surface everywhere, which is the trust mechanism. The component is presentation + state machine only. Every network call goes through a ConnectTransport you implement on your own backend — the parent never sees a secret, token, or signature, and your provider key never reaches the browser.

npm install @phosra/connect

Import	Use
`@phosra/connect`	Web (React) — `PhosraConnect`, `ConnectFlow`, `useConnect`
`@phosra/connect/native`	React Native — same components
`@phosra/connect/core`	Shared types + the headless `useConnect` controller

The transport contract

The component calls your backend through a ConnectTransport. Three calls are required; the fourth (provision) is optional and unlocks in-modal create-and-link. Each maps 1:1 to a createLink connect leg on your BFF.

import type { ConnectTransport } from "@phosra/connect/core"

const transport: ConnectTransport = {
  // → { authorizeUrl, state, sessionId }        (wraps link.connect.start)
  async init(req)     { return post("/api/phosra/connect/init", req) },

  // → { sessionId, childProfiles, provisioningForm? }   (wraps link.connect.resume)
  async complete(req) { return post("/api/phosra/connect/complete", req) },

  // → { grant_id, verified?, receiptFingerprint? }      (wraps link.connect.finish)
  async bind(req)     { return post("/api/phosra/connect/bind", req) },

  // OPTIONAL → { grant_id, verified, provisioned }      (wraps link.provision)
  async provision(req){ return post("/api/phosra/connect/provision", req) },
}

Transport call	Returns	BFF wraps
`init`	`{ authorizeUrl, state, sessionId }`	`link.connect.start(...)`
`complete`	`{ sessionId, childProfiles, provisioningForm? }`	`link.connect.resume(...)`
`bind`	`{ grant_id, verified?, receiptFingerprint? }`	`link.connect.finish(...)`
`provision` (optional)	`{ grant_id, verified, provisioned }`	`link.provision(...)`

verified drives the trust cue — never fake it. Success shows “Verified on the OCSS Trust List” only when verified === true (your BFF confirmed the census signed-receipt actually verified to root). Otherwise the modal shows <Platform> connected — confirming enforcement… (where <Platform> is the platform name). Return verified honestly; a green badge with no verified receipt is the one thing the branding rule forbids.

provisioningForm is server-advertised. If complete returns provisioningForm: "batch", that overrides the component prop — the platform told the census it accepts batch provisioning, and the modal offers the create-and-link step. Your bind / provision handlers deliver signed to the OCSS root; there is no connect secret anywhere in this flow.

Web quickstart

import { PhosraConnect } from "@phosra/connect"
import type { ConnectTransport } from "@phosra/connect/core"

const transport: ConnectTransport = { init, complete, bind, provision }

export function ConnectNotflix() {
  return (
    <PhosraConnect
      provider={{
        did: "did:ocss:custo",
        name: "Custo",
        linkIcon: { lightUrl: custoMark, darkUrl: custoMarkDark, fallbackInitials: "CU" },
      }}
      platform={{
        did: "did:ocss:notflix",
        name: "Notflix",
        linkIcon: { lightUrl: notflixMark, darkUrl: notflixMarkDark, fallbackInitials: "NO" },
      }}
      rules={[{ category: "dm_restriction", label: "Restrict direct messages" }]}
      grantedScope={["dm_restriction"]}
      childId="child:a11ce0fa-..."
      ageHint="13_15"
      childName="Ava"                  // names the child in the grant preview
      redirectUri="https://custo.app/phosra/callback"
      transport={transport}
      onSuccess={(r) => {
        // r.grant_id, r.verified, r.receiptFingerprint
        router.push("/family")
      }}
      onExit={() => router.back()}
    />
  )
}

The two entity icons remain independent. Phosra Link derives each standardized tile from that entity’s approved Mark and composes provider → Phosra → platform at render time; it does not create a combined image or require a separate app-icon upload. The parent sees three earned trust cues rendered as calm badges — “Accredited on the OCSS Trust List” (intro), the concrete rules preview (the real rules you pass), and Verified on <Platform> (only when bind returned verified === true). No secret, no token, no signature is ever surfaced.

Props

Prop	Type	Notes
`platform`	`{ did, name }`	Target platform. `did` gates against the Trust List; `name` co-brands the modal.
`rules`	`{ category, label }[]`	The concrete grant preview — the exact rules the parent is consenting to.
`grantedScope`	`string[]`	The rule categories bound in the grant (drives `bind`).
`childId`	`string`	The OCSS child ref (`child:<uuid>`).
`ageHint`	`AgeHint`	`"under_13" \| "13_15" \| "16_17"`.
`childName`	`string` (opt)	Names the child in the preview and success copy.
`provisioningForm`	`"batch" \| "single"` (opt)	Enables create-and-link; a server-advertised `provisioningForm` from `complete` overrides it.
`provisionChildren`	`ProvisionChild[]` (opt)	Ages/names to create when there are no existing profiles.
`redirectUri`	`string`	Your OAuth callback.
`transport`	`ConnectTransport`	Your BFF calls.
`onSuccess`	`(r: BindResult) => void`	`{ grant_id, verified?, receiptFingerprint? }`.
`onExit`	`() => void`	Parent dismissed the modal.

ConnectFlow takes the identical props if you want the flow inline rather than in a modal shell. React Native is the same API from @phosra/connect/native.

When there are no existing profiles on the platform and you pass a provisioningForm plus a transport.provision, the modal shows a no_profiles step with a “Create & connect” button. The parent creates the banded child profiles and binds them in one contained step — no new tab, no dead-end.

<PhosraConnect
  platform={{ did: "did:ocss:notflix", name: "Notflix" }}
  rules={[{ category: "content_rating", label: "Age-appropriate titles only" }]}
  grantedScope={["content_rating"]}
  childId="child:a11ce0fa-..."
  ageHint="under_13"
  childName="Leo"
  provisioningForm="batch"                    // + transport.provision → in-modal create
  provisionChildren={[{ ageHint: "under_13", displayName: "Leo" }]}
  redirectUri="https://custo.app/phosra/callback"
  transport={transport}
  onSuccess={(r) => router.push("/family")}
  onExit={() => router.back()}
/>

Under the hood the modal advances through two new statuses: no_profiles (the create step is offered) and creating (the signed provision delivery is in flight). Your transport.provision returns { grant_id, verified, provisioned } — provisioned is the count created.

Headless: `useConnect`

For a fully custom UI, drive the state machine directly with useConnect and render your own chrome (branding still required — see below).

import { useConnect } from "@phosra/connect/core"

function CustomConnect() {
  const c = useConnect({
    platform: { did: "did:ocss:notflix", name: "Notflix" },
    grantedScope: ["dm_restriction"],
    childId: "child:a11ce0fa-...",
    ageHint: "13_15",
    provisioningForm: "batch",
    provisionChildren: [{ ageHint: "13_15", displayName: "Ava" }],
    redirectUri: "https://custo.app/phosra/callback",
    transport,
  })

  // c.status: … | "no_profiles" | "creating" | …
  if (c.status === "no_profiles") {
    return <button onClick={() => c.createProfiles()}>Create &amp; connect</button>
  }
  // render per c.status; c.state carries provisioningForm and the child profiles
}

createProfiles() is valid only while status === "no_profiles"; it runs the signed transport.provision and advances the machine.

Branding is mandatory

The drop-ins render the Phosra Link branding — the phosra · OCSS lockup, the “Accredited / Verified on the OCSS Trust List” trust signals, and the never-a-fake-green honesty rule (the verified badge only ever appears when the census receipt actually verified). This is required, not optional: any Phosra Link connect/consent surface MUST use the published kit, a provider may not hand-roll or restyle the branded consent, and the platform auth leg MUST co-brand Phosra Link · <Platform>. Consistency is the trust mechanism, and it is assessed at accreditation. See the Phosra Link Branding Requirement.

Provider · createLink (writer-plane compatibility) — the BFF your transport wraps
@phosra/link → Reference BFF — a copy-pasteable BFF for the three legs
PhosraLinkKit (iOS) — the native equivalent
Phosra Link Branding Requirement

Get Started

Concepts

Guides

Cookbook

Partner Integration

Phosra Link (secret-free)

OCSS Conformance

Platform

@phosra/connect — PhosraConnect

The transport contract

Web quickstart

Props

Headless: `useConnect`

Branding is mandatory

Next

​The transport contract

​Web quickstart

​Props

​Create-and-link in the modal

​Headless: useConnect

​Branding is mandatory

​Next

The transport contract

Web quickstart

Props

Create-and-link in the modal

Headless: `useConnect`

Branding is mandatory

Next