@phosra/link

npm install @phosra/link

import { Pool } from "pg"
import { makePostgresFamilyLinkRuntimeV1 } from "@phosra/link/server"

const familyLink = makePostgresFamilyLinkRuntimeV1({
  database: new Pool({ connectionString: process.env.DATABASE_URL }),
  adapter: destinationAdapter,
  application_origin: "https://app.example-parental-controls.com",
  provider_did: "did:ocss:example-parental-controls",
  client_token_key: Buffer.from(process.env.FAMILY_LINK_TOKEN_KEY!, "base64url"),
  authenticate: authenticateParent,
  children: providerChildAuthority,
  platforms: platformDirectory,
  accounts: destinationAccountAuthority,
  provider_events: {
    signing_key: providerEventSigningKey,
    destination_url: "https://app.example-parental-controls.com/webhooks/phosra-link",
  },
})

await familyLink.migrate()

"use client"

import { useMemo } from "react"
import { createFamilyLink, FamilyPhosraLinkFlow } from "@phosra/link/react"

export function SetUpNotflix({ token }: { token: string }) {
  const client = useMemo(() => createFamilyLink({
    token,
    onPlanAccepted: () => window.dispatchEvent(new Event("family-link:accepted")),
    onExit: () => history.back(),
  }), [token])

  return (
    <FamilyPhosraLinkFlow
      open
      client={client}
      providerDisplayName="Example Parental Controls"
      authenticateDestination={openDestinationAuthorization}
    />
  )
}

// lib/phosra-link-server.ts — server-only shared composition.
// Node-only module; never import from client components.
import { Pool } from "pg"
import {
  createGoldenLinkServer,
  type GoldenLinkServer,
  type ParentLinkDiagnosticV1,
} from "@phosra/link/server"

const database = new Pool({ connectionString: process.env.DATABASE_URL })

function compose(): Promise<GoldenLinkServer> {
  return createGoldenLinkServer({
    credential: process.env.PHOSRA_CREDENTIAL!,
    database,

    authenticate: async (request) => {
      const session = await authenticatedParent(request)
      return session === null ? null : {
        sessionID: session.id,
        parentID: session.parentId,
      }
    },

    children: {
      resolve: async ({ principal, childRef }) => {
        const child = await childForParent(principal.parentID, childRef)
        // `id` is the CENSUS child id, not your own row id. See below.
        if (child === null || child.censusChildRef === null) return null
        return {
          id: child.censusChildRef,
          displayName: child.displayName,
          ageBand: child.ageBand,
          householdRef: child.familyId,
        }
      },
    },

    policy: {
      resolve: async ({ child, platformDid }) => {
        const maxAllowed = await contentRatingCeiling(child.id, platformDid)
        if (maxAllowed === null) return null
        return [{
          category: "content_rating",
          config: {
            family: "numeric_threshold",
            scale: "ratings_age",
            max_allowed: maxAllowed,
          },
        }]
      },
    },

    // The only channel that carries WHY a ceremony failed. Wire it on day one.
    onDiagnostic: (diagnostic: ParentLinkDiagnosticV1) => {
      console.error(JSON.stringify({ event: "phosra_link_diagnostic", ...diagnostic }))
    },
  })
}

let pending: Promise<GoldenLinkServer> | undefined

/**
 * One shared server for every route and the worker. A failed bootstrap clears
 * itself, so the next request retries instead of inheriting a dead module.
 */
export function getPhosraLinkServer(): Promise<GoldenLinkServer> {
  if (!pending) {
    const attempt = Promise.resolve().then(compose)
    pending = attempt
    void attempt.catch(() => {
      if (pending === attempt) pending = undefined
    })
  }
  return pending
}

// app/api/phosra/link/[...phosra]/route.ts
import { getPhosraLinkServer } from "@/lib/phosra-link-server"

export const runtime = "nodejs"
export const dynamic = "force-dynamic"

async function dispatch(request: Request): Promise<Response> {
  const server = await getPhosraLinkServer()
  return server.handler(request)
}

export const GET = dispatch
export const POST = dispatch
export const DELETE = dispatch

return [{
  category: "content_rating",
  config: {
    family: "numeric_threshold",
    scale: "ratings_age",
    max_allowed: 13,        // integer, 0–21
  },
}]

// scripts/phosra-link-worker.ts — separate server process entry point
import { getPhosraLinkServer } from "../lib/phosra-link-server"

const shutdown = new AbortController()
process.once("SIGTERM", () => shutdown.abort())
process.once("SIGINT", () => shutdown.abort())

const server = await getPhosraLinkServer()
await server.runWorker({ signal: shutdown.signal })

node --import tsx scripts/phosra-link-worker.ts

import { PhosraLink } from "@phosra/link/react"
import { useRouter } from "next/navigation"

const router = useRouter()

<PhosraLink
  createSession={async ({ signal }) => {
    const response = await fetch("/api/phosra/link/sessions", {
      method: "POST",
      signal,
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        platform_did: selectedPlatformDid,
        child_ref: selectedChildId,
        return_to: window.location.pathname,
      }),
    })
    // Keep the refusal code. It is the difference between "try again" and
    // "this app is misconfigured and retrying can never work".
    if (!response.ok) throw new PhosraLinkSessionStartError(response.status, await refusalCode(response))
    return response.json()
  }}
  onEvent={recordLinkEvent}
  onExit={(reason) => {
    setOpen(false)
    if (reason === "linked" || reason === "completed") router.refresh()
  }}
/>

"use client"

export class PhosraLinkSessionStartError extends Error {
  readonly code?: string
  readonly status: number
  constructor(status: number, code?: string) {
    super(`Unable to start Phosra Link (${status}${code ? `: ${code}` : ""})`)
    this.name = "PhosraLinkSessionStartError"
    this.status = status
    this.code = code
  }
}

/** Read `error.code` off a refusal body without trusting its shape. */
export async function refusalCode(response: Response): Promise<string | undefined> {
  try {
    const body: unknown = await response.json()
    if (body === null || typeof body !== "object") return undefined
    const error = (body as Record<string, unknown>).error
    if (error === null || typeof error !== "object") return undefined
    const code = (error as Record<string, unknown>).code
    return typeof code === "string" && code.length > 0 && code.length <= 64 ? code : undefined
  } catch {
    return undefined
  }
}

import { makeLinkStore } from "@phosra/link"

// The same Pool you passed to createGoldenLinkServer — these are its own tables.
const grants = makeLinkStore(database)

// targetRef is always `child:<census child uuid>` — the same id children.resolve returns.
const targetRef = `child:${authorizedChild.censusChildRef}`

const exact = (await grants.listGrantsByChild(targetRef)).filter(
  (grant) =>
    grant.grant_id === requestedGrantId &&
    grant.audience_did === requestedPlatformDid &&
    grant.target_ref === targetRef &&
    grant.status === "active",
)
if (exact.length !== 1) throw new Error("LINK_RECOVERY_NOT_FOUND")

const authority = {
  grantId: requestedGrantId,
  platformDid: requestedPlatformDid,
  targetRef,
}

const server = await getPhosraLinkServer()

// Resume: replay the exact frozen delivery for this authorized grant.
// A grant still in `finishing` needs the parent's live principal.
const resumed = await server.retryGrant(authority, {
  sessionID: session.id,
  parentID: session.parentId,
})

// Start over: clear an incomplete connection so a fresh ceremony can begin.
const outcome = await server.restartIncompleteGrant(authority)
// "abandoned" | "revoked" | null — null means there was nothing safe to clear.

const authority = {
  grantId: savedConnection.grantId,
  platformDid: savedConnection.platformDid,
  targetRef: `child:${authorizedChild.censusChildRef}`,
}

const server = await getPhosraLinkServer()
const projection = await server.retryPlatformForGrant(authority)
if (projection === null) throw new Error("Platform sync is not available")

// scripts/phosra-migrate.mjs — run after your own migrations, before the app boots.
import { migrateLinkServerSchema } from "@phosra/link/server"
import { Pool } from "pg"

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
try {
  await migrateLinkServerSchema(pool)
} finally {
  await pool.end()
}

# .env.local — never commit; these are sandbox-only test credentials
PHOSRA_CREDENTIAL="phosra_cred_v3.…"        # minted for http://localhost:3005
DATABASE_URL="postgres://…/your_local_db"    # your own local database