@phosra/connect 0.1.0

package/README.md

@@ -0,0 +1,313 @@
+# @phosra/connect
+
+Phosra Connect is a Plaid Link-style embeddable flow that lets a parent authorize safety rules on an enforcement platform (e.g. Snaptr) directly inside a parental-controls app (PCA). It has three layers: a headless `useConnect` hook (in `@phosra/connect/core`) that drives the full ceremony state machine; an unstyled `ConnectFlow` reference component with stable `data-phosra-connect` hooks for custom styling; and a styled `PhosraConnect` drop-in that ships the approved Phosra design out of the box. Both web (React DOM) and React Native are supported via separate entry points. The package ships as TypeScript source and runs entirely inside the PCA app's own trust boundary — there is no Phosra-hosted page or iframe. The component calls only the PCA's own BFF routes, which wrap `@phosra/link` server-side; the browser never talks to Phosra directly and never sees the `endpoint_id_label` (the enforcement handle). The ceremony is router-blind: Phosra verifies signed enforcement receipts but cannot read message content. The safety path is never metered, rate-limited, or blocked.
+
+---
+
+## Install
+
+```
+npm install @phosra/connect
+```
+
+Peer dependencies for web: `react ^18 || ^19`, `react-dom ^18 || ^19`.
+
+Peer dependencies for React Native (additional): `react-native`, `react-native-svg`, `expo-web-browser`.
+
+**This package ships as TypeScript source** (so it compiles into your bundle and runs on your own origin — never a Phosra-hosted script). Your bundler transpiles it:
+
+- **React Native / Metro** and **Vite** — works out of the box.
+- **Next.js** — add the package to `transpilePackages`:
+  ```js
+  // next.config.js
+  module.exports = { transpilePackages: ['@phosra/connect'] };
+  ```
+
+---
+
+## Entry Points
+
+| Import | Contents |
+|--------|----------|
+| `@phosra/connect` | `PhosraConnect` + `ConnectFlow` + all core types (web default) |
+| `@phosra/connect/web` | Same, explicit web entry |
+| `@phosra/connect/core` | `useConnect` hook, `createConnectController`, all shared types — no UI |
+| `@phosra/connect/native` | `PhosraConnect` for React Native (needs `react-native-svg`) |
+| `@phosra/connect/connect.css` | Default styles for the web drop-in; import once in your app root |
+
+---
+
+## Web Usage
+
+```tsx
+import '@phosra/connect/connect.css';
+import { PhosraConnect } from '@phosra/connect';
+import type { ConnectTransport } from '@phosra/connect/core';
+
+const transport: ConnectTransport = {
+  async init(req) {
+    const res = await fetch('/api/phosra/connect/init', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(req),
+    });
+    if (!res.ok) throw new Error(await res.text());
+    return res.json();
+  },
+  async complete(req) {
+    const res = await fetch('/api/phosra/connect/complete', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(req),
+    });
+    if (!res.ok) throw new Error(await res.text());
+    return res.json();
+  },
+  async bind(req) {
+    const res = await fetch('/api/phosra/connect/bind', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(req),
+    });
+    if (!res.ok) throw new Error(await res.text());
+    return res.json(); // { grant_id }
+  },
+};
+
+export default function ConnectPage() {
+  return (
+    <PhosraConnect
+      platform={{ did: 'did:ocss:snaptr', name: 'Snaptr' }}
+      rules={[
+        { category: 'addictive_pattern_block', label: 'Block addictive feed patterns' },
+        { category: 'dm_restriction', label: 'Restrict direct messages' },
+      ]}
+      grantedScope={['addictive_pattern_block', 'dm_restriction']}
+      redirectUri="https://yourapp.com/phosra/callback"
+      transport={transport}
+      onSuccess={(result) => console.log('connected, grant_id:', result.grant_id)}
+      onExit={() => router.back()}
+    />
+  );
+}
+```
+
+### Optional props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `childId` | `string` | — (parent picks from list) |
+| `ageHint` | `'under_13' \| '13_15' \| '16_17'` | — |
+| `openAuthorizeUrl` | `AuthorizeOpener` | Same-origin popup + postMessage |
+| `platformGlyph` | `React.ReactNode` | Generic platform glyph |
+
+---
+
+## React Native Usage
+
+```tsx
+import { PhosraConnect } from '@phosra/connect/native';
+// transport shape is identical to the web example above.
+
+export default function ConnectScreen({ navigation }) {
+  return (
+    <PhosraConnect
+      platform={{ did: 'did:ocss:snaptr', name: 'Snaptr' }}
+      rules={[
+        { category: 'addictive_pattern_block', label: 'Block addictive feed patterns' },
+      ]}
+      grantedScope={['addictive_pattern_block']}
+      redirectUri="yourapp://phosra/callback"
+      transport={transport}
+      onSuccess={(result) => navigation.navigate('Success', { grantId: result.grant_id })}
+      onExit={() => navigation.goBack()}
+    />
+  );
+}
+```
+
+Additional peer dependencies for React Native: `react-native-svg` (for icons) and `expo-web-browser` (for the in-app browser opener). The component injects a native `AuthorizeOpener` automatically when running on React Native; pass `openAuthorizeUrl` to override.
+
+---
+
+## The BFF Contract
+
+**This is the load-bearing section.** The `ConnectTransport` interface maps directly onto three route handlers that your BFF implements. Your BFF wraps `@phosra/link` server-side. The component never talks to Phosra or to the platform directly.
+
+The three `@phosra/link` server functions in play:
+
+| `@phosra/link` function | Transport call | Role |
+|-------------------------|----------------|------|
+| `initPlatformOAuth` | `transport.init` | PKCE S256 authorize URL + state |
+| `completePlatformOAuth` | `transport.complete` | Code exchange + child-profile list |
+| `bindProfile` + `runConnectCeremony` | `transport.bind` | Bind child, mint consent, provision enforcement endpoint, deliver label to platform |
+
+### Shared config (once at startup)
+
+```ts
+// lib/phosra-link.ts
+import type { LinkConfig } from '@phosra/link';
+import { loadSenderKey } from '@openchildsafety/ocss';
+import { pool } from './db'; // your pg Pool
+
+export const linkCfg: LinkConfig = {
+  censusBaseUrl:    process.env.PHOSRA_CENSUS_URL!,
+  trustRootXB64Url: process.env.PHOSRA_TRUST_ROOT_X!,
+  parentKey:        loadSenderKey(process.env.PARENT_SIGNING_KEY_PEM!),
+  writerKey:        loadSenderKey(process.env.WRITER_SIGNING_KEY_PEM!),
+  writerDid:        process.env.WRITER_DID!,
+  routerDid:        process.env.ROUTER_DID!,
+  householdSecret:  process.env.HOUSEHOLD_SECRET!,
+  pool,
+  developerOrgId:   process.env.PHOSRA_DEVELOPER_ORG_ID, // from your Phosra dashboard
+};
+```
+
+### `POST /api/phosra/connect/init`
+
+Generates a PKCE S256 pair, stores a `pending` platform session, and returns the authorize URL.
+
+```ts
+// app/api/phosra/connect/init/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { initPlatformOAuth } from '@phosra/link';
+import { linkCfg } from '@/lib/phosra-link';
+import { getServerSession } from '@/lib/auth'; // your parent auth
+
+export async function POST(req: NextRequest) {
+  const { platformDid, redirectUri, grantedScope, ageHint, childId } = await req.json();
+  const session = await getServerSession(req); // authenticated parent session
+
+  const result = await initPlatformOAuth(linkCfg, {
+    platformDid,
+    redirectUri,
+    parentSessionRef: session.id, // binds state to the authenticated parent (CSRF defense)
+    childHint: childId,           // optional login_hint for the platform
+  });
+
+  // Returns: { authorizeUrl: string, state: string, sessionId: string }
+  return NextResponse.json(result);
+}
+```
+
+### `POST /api/phosra/connect/complete`
+
+Entirely server-side: verifies `state` (CSRF + session-fixation defense), performs the PKCE code exchange with the platform (code_verifier stays server-side, never reaches the client — GC5), fetches and stores the child-profile list, then discards the access token.
+
+```ts
+// app/api/phosra/connect/complete/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { completePlatformOAuth } from '@phosra/link';
+import { linkCfg } from '@/lib/phosra-link';
+import { getServerSession } from '@/lib/auth';
+
+export async function POST(req: NextRequest) {
+  const { code, state, sessionId } = await req.json();
+  const session = await getServerSession(req);
+
+  const result = await completePlatformOAuth(linkCfg, {
+    code,
+    state,
+    parentSessionRef: session.id,
+  });
+
+  // Returns: { sessionId: string, childProfiles: ChildProfile[] }
+  // ChildProfile: { id: string, displayName: string, ageHint?: number }
+  return NextResponse.json(result);
+}
+```
+
+### `POST /api/phosra/connect/bind`
+
+The ceremony's final leg. `bindProfile` records the parent's confirmed child pick and returns a `LinkSession`. `runConnectCeremony` then calls `completeLink` (mints the consent attestation and provisions the §9.3(b) enforcement endpoint signed by the writer key), then calls your `deliver` closure to POST the `endpoint_id_label` server-to-server to the platform's callback. **The `endpoint_id_label` never reaches the browser. The route returns only `{ grant_id }`.**
+
+```ts
+// app/api/phosra/connect/bind/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { bindProfile, runConnectCeremony, deliverLabelToPlatform } from '@phosra/link';
+import { linkCfg } from '@/lib/phosra-link';
+
+// Your registry mapping a platform DID to its server-side callback URL.
+function resolvePlatformCallbackUrl(platformDid: string): string {
+  const registry: Record<string, string> = {
+    'did:ocss:snaptr': 'https://api.snaptr.example/ocss/connect-callback',
+  };
+  const url = registry[platformDid];
+  if (!url) throw new Error(`unknown platform: ${platformDid}`);
+  return url;
+}
+
+export async function POST(req: NextRequest) {
+  const { sessionId, platformChildProfileId, childId, grantedScope, ageHint } = await req.json();
+
+  // Leg 1: record the parent's child pick, advance platform session → bound,
+  // produce a LinkSession ready for completeLink.
+  const linkSession = await bindProfile(linkCfg, {
+    sessionId,
+    platformChildProfileId,
+    childId,
+    granted_scope: grantedScope,  // note: snake_case in @phosra/link
+    ageHint,
+  });
+
+  const platformCallbackUrl = resolvePlatformCallbackUrl(linkSession.audience_did);
+
+  // Leg 2: completeLink (consent + endpoint) then deliver the label server-to-server.
+  // runConnectCeremony calls completeLink internally; your deliver closure is called
+  // with the cleartext endpoint_id_label exactly once.
+  const { grant_id } = await runConnectCeremony(
+    linkCfg,
+    linkSession,
+    async (endpoint_id_label) => {
+      const r = await deliverLabelToPlatform(platformCallbackUrl, {
+        endpoint_id_label,
+        state: sessionId, // correlates to the platform's active session
+      });
+      if (!r.ok) throw new Error(`platform callback failed: ${r.status}`);
+    },
+  );
+
+  // endpoint_id_label is consumed by the deliver closure and never returned.
+  return NextResponse.json({ grant_id });
+}
+```
+
+`grant_id` is the value surfaced to your `onSuccess` callback as `result.grant_id`.
+
+---
+
+## Redirect Page (Web)
+
+The authorize popup (or tab) lands on the `redirectUri` on **your own origin**. That page reads `code` and `state` from the query string, postMessages them back to the opener, and closes. Nothing Phosra-specific is required here — it is a standard OAuth redirect receiver.
+
+```html
+<!-- public/phosra/callback/index.html  (or a minimal Next.js page at /phosra/callback) -->
+<script>
+  const params = new URLSearchParams(location.search);
+  const code  = params.get('code');
+  const state = params.get('state');
+  if (window.opener && code && state) {
+    window.opener.postMessage(
+      { type: 'phosra-connect', code, state },
+      window.location.origin,    // same-origin only
+    );
+    window.close();
+  }
+</script>
+```
+
+The component's built-in `createWebAuthorizeOpener` opens the popup and listens for `{ type: 'phosra-connect' }` from the same origin. If you use a mobile deep-link scheme or a custom web-view, pass a custom `openAuthorizeUrl` prop (an `AuthorizeOpener`) to `PhosraConnect` — it receives `(authorizeUrl, redirectUri)` and must resolve to `{ code, state }` or `{ canceled: true }`.
+
+---
+
+## Honesty and Trust Boundary
+
+**Never a fake green.** The success screen ("Verified on the OCSS Trust List") is shown only after the census returns a signed write receipt that verifies to the OCSS trust root. The component displays "Enforced" only on a confirmed `success` status from the ceremony — never on a client-side flag or an optimistic assumption.
+
+**Router-blind.** Phosra verifies enforcement receipts (what rule applied, to which child, on which platform) but is structurally prevented from reading message content. The §3A.3 harm-context lane is sealed end-to-end; Phosra is on the signal-and-receipt path, not the content path.
+
+**Ships as source, runs on your domain.** There is no Phosra-hosted page, iframe, or remotely loaded script. You review the source, you bundle it, it runs inside your application's trust boundary. The component's `transport` calls go to your own BFF routes; no browser request is ever made to Phosra infrastructure directly.
+
+**The safety path is never metered or blocked.** `@phosra/link` enforces rule writes unconditionally once a valid grant exists. Billing applies to the grant lifecycle (connecting and managing integrations), not to individual safety-rule evaluations. An expired or suspended billing state cannot prevent a rule from being applied to a child's account.
+
+**No hidden failures.** The controller never leaves the parent on a spinner that hides an error: a blocked popup, a rejected webview, or a failed BFF call all surface as an honest `error` state with a retry. The web opener rejects if the browser blocks the popup. Because the `transport` fetches are yours, **give each one an `AbortSignal`/timeout** so a stalled network also fails into the error state rather than spinning forever — the component honors whatever your transport throws.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@phosra/connect",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Embeddable Phosra Connect component — the Plaid Link for parental-controls apps. Headless hook + unstyled reference + styled drop-in, web and React Native. Ships as source; runs in the PCA app's own trust boundary.",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core/index.ts",
+    "./web": "./src/web/index.ts",
+    "./native": "./src/native/index.ts",
+    "./connect.css": "./src/web/connect.css"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/tsconfig.json",
+    "!**/vitest.config.ts",
+    "!src/native/react-native.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit && tsc -p src/native/tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "react-native": "*",
+    "react-native-svg": "*"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/react": "^19",
+    "vitest": "^1.6.1"
+  }
+}

package/src/core/controller.ts

@@ -0,0 +1,186 @@
+import type {
+  ConnectController,
+  ConnectControllerOptions,
+  ConnectState,
+  ConnectStatus,
+} from './types.js';
+
+/**
+ * Framework-agnostic state machine for the Phosra Connect ceremony. No React,
+ * no DOM, no React Native — the transport (3 BFF calls) and the "open secure
+ * webview" primitive are injected, so this single controller drives both the web
+ * and the native rendering layers. `useConnect` is a thin React adapter over it.
+ *
+ * Flow: idle → authorizing (init + webview) → exchanging (PKCE complete) →
+ * selecting (child picker) → binding (mint consent + provision endpoint) → success.
+ * Any failure lands in `error{stage}`; `retry()` re-enters from that stage.
+ *
+ * Cancellation is epoch-guarded: every run captures the current `epoch`, and
+ * `cancel()`/`retry()`/`open()` bump it. After each await, a leg bails if its
+ * epoch is stale, so a ceremony the parent canceled can never resume, bind a
+ * child, or fire onSuccess after onExit.
+ */
+export function createConnectController(opts: ConnectControllerOptions): ConnectController {
+  let state: ConnectState = { status: 'idle' };
+  const listeners = new Set<(s: ConnectState) => void>();
+
+  // Ceremony context threaded across legs.
+  let sessionId: string | undefined;
+  let lastProfileId: string | undefined;
+  // Monotonic run epoch; bumped by open/retry/cancel. A leg with a stale epoch
+  // aborts on its next await boundary and never mutates state.
+  let epoch = 0;
+
+  function set(next: Partial<ConnectState> & { status: ConnectStatus }): void {
+    // Replace wholesale so stale fields (childProfiles, error, result) never leak
+    // across unrelated transitions; callers pass exactly what the new state carries.
+    state = { ...next };
+    for (const fn of listeners) fn(state);
+  }
+
+  const stale = (gen: number): boolean => gen !== epoch;
+
+  function fail(gen: number, stage: ConnectStatus, err: unknown): void {
+    if (stale(gen)) return; // a canceled/superseded run must not clobber state
+    const message = err instanceof Error ? err.message : String(err);
+    const error = { stage, message };
+    set({ status: 'error', error });
+    opts.onError?.(error);
+  }
+
+  async function runAuthorize(gen: number): Promise<void> {
+    set({ status: 'authorizing' });
+    let init;
+    try {
+      init = await opts.transport.init({
+        platformDid: opts.platform.did,
+        childId: opts.childId,
+        grantedScope: opts.grantedScope,
+        ageHint: opts.ageHint,
+      });
+    } catch (err) {
+      fail(gen, 'authorizing', err);
+      return;
+    }
+    if (stale(gen)) return;
+    sessionId = init.sessionId;
+
+    let opened;
+    try {
+      opened = await opts.openAuthorizeUrl(init.authorizeUrl, opts.redirectUri);
+    } catch (err) {
+      fail(gen, 'authorizing', err);
+      return;
+    }
+    if (stale(gen)) return;
+    if ('canceled' in opened) {
+      set({ status: 'canceled' });
+      opts.onExit?.();
+      return;
+    }
+    // Defense-in-depth CSRF check (the server's complete() is authoritative).
+    if (opened.state !== init.state) {
+      fail(gen, 'authorizing', new Error('Security check failed. Please try again.'));
+      return;
+    }
+    await runExchange(gen, opened.code, opened.state);
+  }
+
+  async function runExchange(gen: number, code: string, oauthState: string): Promise<void> {
+    if (!sessionId) {
+      fail(gen, 'exchanging', new Error('missing session'));
+      return;
+    }
+    set({ status: 'exchanging' });
+    let done;
+    try {
+      done = await opts.transport.complete({ code, state: oauthState, sessionId });
+    } catch (err) {
+      fail(gen, 'exchanging', err);
+      return;
+    }
+    if (stale(gen)) return;
+    sessionId = done.sessionId;
+    set({ status: 'selecting', childProfiles: done.childProfiles });
+
+    // Auto-advance only when there is exactly one profile AND the caller already
+    // named the child — otherwise the parent must confirm which account.
+    if (done.childProfiles.length === 1 && opts.childId) {
+      await runBind(gen, done.childProfiles[0].id);
+    }
+  }
+
+  async function runBind(gen: number, profileId: string): Promise<void> {
+    if (!sessionId) {
+      fail(gen, 'binding', new Error('missing session'));
+      return;
+    }
+    lastProfileId = profileId;
+    set({ status: 'binding' });
+    let bound;
+    try {
+      bound = await opts.transport.bind({
+        sessionId,
+        platformChildProfileId: profileId,
+        childId: opts.childId ?? profileId,
+        grantedScope: opts.grantedScope,
+        ageHint: opts.ageHint,
+      });
+    } catch (err) {
+      fail(gen, 'binding', err);
+      return;
+    }
+    if (stale(gen)) return;
+    set({ status: 'success', result: bound });
+    opts.onSuccess?.(bound);
+  }
+
+  // Defined as locals so both `open` and `retry` can invoke them without relying
+  // on `this` (the hook destructures these methods).
+  async function openImpl(): Promise<void> {
+    if (state.status === 'authorizing' || state.status === 'exchanging' || state.status === 'binding') {
+      return; // already in flight
+    }
+    sessionId = undefined;
+    lastProfileId = undefined;
+    await runAuthorize(++epoch);
+  }
+
+  async function selectChildImpl(profileId: string): Promise<void> {
+    if (state.status !== 'selecting') return;
+    await runBind(epoch, profileId); // continuation of the current run
+  }
+
+  async function retryImpl(): Promise<void> {
+    const stage = state.error?.stage;
+    const gen = ++epoch;
+    if (stage === 'binding' && lastProfileId) {
+      await runBind(gen, lastProfileId);
+    } else {
+      sessionId = undefined;
+      lastProfileId = undefined;
+      await runAuthorize(gen);
+    }
+  }
+
+  function cancelImpl(): void {
+    if (state.status === 'success') return;
+    epoch++; // invalidate any in-flight leg so it can't resume post-cancel
+    set({ status: 'canceled' });
+    opts.onExit?.();
+  }
+
+  return {
+    getState: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+    open: openImpl,
+    selectChild: selectChildImpl,
+    retry: retryImpl,
+    cancel: cancelImpl,
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,19 @@
+export { createConnectController } from './controller.js';
+export { useConnect } from './useConnect.js';
+export type { UseConnectResult } from './useConnect.js';
+export type {
+  AgeHint,
+  ChildProfile,
+  ConnectRule,
+  ConnectPlatform,
+  InitResult,
+  CompleteResult,
+  BindResult,
+  ConnectTransport,
+  AuthorizeOpener,
+  ConnectStatus,
+  ConnectError,
+  ConnectState,
+  ConnectControllerOptions,
+  ConnectController,
+} from './types.js';