@orangecheck/me-client 0.6.0 → 0.8.0

package/README.md

@@ -1,9 +1,23 @@
 # @orangecheck/me-client
 
-Drop-in client for [me.ochk.io](https://me.ochk.io). Sign-in-with-OC button, session lifecycle hooks, payment authorization, developer telemetry, and the canonical billable-event taxonomy as TypeScript types.
+Drop-in client for [me.ochk.io](https://me.ochk.io). Sign-in-with-OC button, popup signin orchestrator, framework-agnostic server-side verification, session lifecycle hooks, payment authorization, webhook signature verification, the canonical billable-event taxonomy as TypeScript types.
 
 > You pay for sessions and actions, not for clicks.
 
+## Three entry points, three audiences
+
+```ts
+// React surface (provider, hook, button, oc.session/payment/event/config/webhook)
+import { useOcSession, oc } from '@orangecheck/me-client';
+
+// Server-side verification — Next.js, Express, Hono. Zero env vars,
+// zero JWK handling. SDK lazy-fetches and caches the JWKS.
+import { withOcAuth, ocAuthExpress, ocAuthHono } from '@orangecheck/me-client/server';
+
+// Browser-only popup orchestrator — same shape Google / GitHub use.
+import { signInWithOc } from '@orangecheck/me-client/popup';
+```
+
 ## Install
 
 ```sh
@@ -120,6 +134,80 @@ import type {
 
 The canonical source of truth lives at [oc-me-web/src/lib/events/types.ts](https://github.com/orangecheck/oc-me-web/blob/main/src/lib/events/types.ts). This package mirrors that shape — any change there ships here in the next minor.
 
+## Server-side verification
+
+Verify the OC session on your backend without writing a JWK fetcher, an env-var loader, or a cache. The SDK does that internally.
+
+### Next.js Pages Router
+
+```ts
+// pages/api/me.ts
+import { withOcAuth } from '@orangecheck/me-client/server';
+
+export default withOcAuth(async (req, res) => {
+    if (!req.ocSession) return res.status(401).json({ ok: false });
+    res.status(200).json({
+        account: {
+            id: req.ocSession.sub,
+            address: req.ocSession.addr,
+            display_name: req.ocSession.name ?? null,
+        },
+    });
+});
+```
+
+Pass `{ required: true }` to short-circuit unauthenticated requests with a 401 before your handler runs.
+
+### Express
+
+```ts
+import express from 'express';
+import { ocAuthExpress } from '@orangecheck/me-client/server';
+
+const app = express();
+app.use(ocAuthExpress());
+
+app.get('/api/profile', (req, res) => {
+    if (!req.ocSession) return res.status(401).json({ error: 'sign in' });
+    res.json({ address: req.ocSession.addr });
+});
+```
+
+### Hono / Cloudflare Workers / Bun / Deno
+
+```ts
+import { Hono } from 'hono';
+import { ocAuthHono } from '@orangecheck/me-client/server';
+
+const app = new Hono();
+app.use('*', ocAuthHono());
+
+app.get('/api/me', (c) => {
+    const session = c.get('ocSession');
+    if (!session) return c.json({ ok: false }, 401);
+    return c.json({ address: session.addr });
+});
+```
+
+`getOcSession(headers)` is the framework-agnostic primitive: pass a Web `Headers` object or a plain `{ cookie, authorization }` object. Cookie auth (family `*.ochk.io`) and Bearer auth (cross-domain) are handled identically.
+
+## Browser popup signin
+
+```tsx
+import { signInWithOc } from '@orangecheck/me-client/popup';
+
+button.addEventListener('click', async () => {
+    const result = await signInWithOc();
+    if (!result) return; // user cancelled or popup blocked
+    // Cross-domain integrators only — same-origin family integrators
+    // (.ochk.io) skip this; the cookie rides automatically.
+    localStorage.setItem('oc-token', result.token);
+    location.assign('/dashboard');
+});
+```
+
+`signInWithOc()` MUST be called inside a user-gesture handler (browsers block `window.open` outside of gestures). Returns `{ account, token }` on success, `null` on cancel / popup block / abort. Pins both `event.origin` AND `event.source === popup` on the postMessage handler so a same-origin attacker can't settle the promise.
+
 ## Custom origin
 
 For staging, self-hosted me-equivalents, or local dev:

package/dist/index.d.mts

@@ -1,6 +1,30 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 
+interface VerifyResult {
+    ok: boolean;
+    reason?: string;
+}
+interface OcPublicJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+    kid: string;
+    alg?: 'EdDSA';
+    use?: 'sig';
+}
+interface VerifyOptions {
+    issuer?: string;
+    jwk?: OcPublicJwk;
+    jwksCacheTtlMs?: number;
+}
+declare function verify(rawBody: string | Uint8Array, sigHex: string, kid: string, options?: VerifyOptions): Promise<VerifyResult>;
+declare function fetchJwksForce(issuer?: string): Promise<void>;
+declare const webhook: {
+    verify: typeof verify;
+    fetchJwks: typeof fetchJwksForce;
+};
+
 declare const PLATFORM_FEE_POLICY: {
     readonly pct: 0.2;
     readonly min_floor_sats: 1;
@@ -99,6 +123,38 @@ interface TelemetryEvent {
     timestamp: string;
     session_id?: string;
 }
+type FederationStatus = 'recruiting' | 'forming' | 'binding' | 'live';
+interface Federation {
+    slug: string;
+    name: string;
+    status: FederationStatus;
+    threshold: string;
+    target_guardian_count: number;
+    invite: string | null;
+    charter_hash: string | null;
+    last_attestation_at: string | null;
+    geography_hint: string;
+    geography_requirements?: string;
+    charter_status?: string;
+    ceremony_window?: string;
+    why_this_one?: string;
+    apply_cta?: string;
+    apply_href?: string;
+}
+type SigningMethod = 'fedimint_threshold' | 'fedimint_client' | 'bip322';
+
+interface FireEventOptions {
+    project_key: string;
+    subtype: EventSubtype;
+    action_label?: string;
+    payment_amount_sats?: number;
+    user_address?: string;
+    metadata?: Record<string, unknown>;
+}
+declare function fire(options: FireEventOptions): Promise<BillableEvent>;
+declare const event: {
+    fire: typeof fire;
+};
 
 interface OcSignInButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onError'> {
     scope: string[];
@@ -125,8 +181,27 @@ declare const payment: {
     authorize: typeof authorize;
 };
 
+declare function validate(cfg: IntegratorPriceConfig): ValidationResult;
+declare const config: {
+    validate: typeof validate;
+};
+
+declare function list(): Promise<Federation[]>;
+declare function live(): Promise<Federation[]>;
+declare function get(slug: string): Promise<Federation | null>;
+declare function defaultLive(): Promise<Federation | null>;
+declare const federations: {
+    list: typeof list;
+    live: typeof live;
+    get: typeof get;
+    defaultLive: typeof defaultLive;
+};
+
 declare function setOrigin(url: string): void;
 declare function getOrigin(): string;
+declare function setBearerToken(token: string | null): void;
+declare function getBearerToken(): string | null;
+declare function clearBearerToken(): void;
 declare class MeClientError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
@@ -141,6 +216,22 @@ declare const oc: {
     payment: {
         authorize: (opts: PaymentAuthorizeOptions) => Promise<PaymentResult>;
     };
+    event: {
+        fire: (options: FireEventOptions) => Promise<BillableEvent>;
+    };
+    config: {
+        validate: (cfg: IntegratorPriceConfig) => ValidationResult;
+    };
+    webhook: {
+        verify: typeof verify;
+        fetchJwks: typeof fetchJwksForce;
+    };
+    federations: {
+        list: () => Promise<Federation[]>;
+        live: () => Promise<Federation[]>;
+        get: (slug: string) => Promise<Federation | null>;
+        defaultLive: () => Promise<Federation | null>;
+    };
 };
 
-export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type Session, type SessionPolicy, type SignInOptions, type SiteFeeShape, type TelemetryEvent, type ValidationResult, computeFees, getOrigin, oc, onTelemetry, payment, session, setOrigin, validateIntegratorConfig };
+export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type Federation, type FederationStatus, type FireEventOptions, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type Session, type SessionPolicy, type SignInOptions, type SigningMethod, type SiteFeeShape, type TelemetryEvent, type ValidationResult, type VerifyOptions, type VerifyResult, clearBearerToken, computeFees, config, event, federations, getBearerToken, getOrigin, oc, onTelemetry, payment, session, setBearerToken, setOrigin, validateIntegratorConfig, webhook };

package/dist/index.d.ts

@@ -1,6 +1,30 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 
+interface VerifyResult {
+    ok: boolean;
+    reason?: string;
+}
+interface OcPublicJwk {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+    kid: string;
+    alg?: 'EdDSA';
+    use?: 'sig';
+}
+interface VerifyOptions {
+    issuer?: string;
+    jwk?: OcPublicJwk;
+    jwksCacheTtlMs?: number;
+}
+declare function verify(rawBody: string | Uint8Array, sigHex: string, kid: string, options?: VerifyOptions): Promise<VerifyResult>;
+declare function fetchJwksForce(issuer?: string): Promise<void>;
+declare const webhook: {
+    verify: typeof verify;
+    fetchJwks: typeof fetchJwksForce;
+};
+
 declare const PLATFORM_FEE_POLICY: {
     readonly pct: 0.2;
     readonly min_floor_sats: 1;
@@ -99,6 +123,38 @@ interface TelemetryEvent {
     timestamp: string;
     session_id?: string;
 }
+type FederationStatus = 'recruiting' | 'forming' | 'binding' | 'live';
+interface Federation {
+    slug: string;
+    name: string;
+    status: FederationStatus;
+    threshold: string;
+    target_guardian_count: number;
+    invite: string | null;
+    charter_hash: string | null;
+    last_attestation_at: string | null;
+    geography_hint: string;
+    geography_requirements?: string;
+    charter_status?: string;
+    ceremony_window?: string;
+    why_this_one?: string;
+    apply_cta?: string;
+    apply_href?: string;
+}
+type SigningMethod = 'fedimint_threshold' | 'fedimint_client' | 'bip322';
+
+interface FireEventOptions {
+    project_key: string;
+    subtype: EventSubtype;
+    action_label?: string;
+    payment_amount_sats?: number;
+    user_address?: string;
+    metadata?: Record<string, unknown>;
+}
+declare function fire(options: FireEventOptions): Promise<BillableEvent>;
+declare const event: {
+    fire: typeof fire;
+};
 
 interface OcSignInButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onError'> {
     scope: string[];
@@ -125,8 +181,27 @@ declare const payment: {
     authorize: typeof authorize;
 };
 
+declare function validate(cfg: IntegratorPriceConfig): ValidationResult;
+declare const config: {
+    validate: typeof validate;
+};
+
+declare function list(): Promise<Federation[]>;
+declare function live(): Promise<Federation[]>;
+declare function get(slug: string): Promise<Federation | null>;
+declare function defaultLive(): Promise<Federation | null>;
+declare const federations: {
+    list: typeof list;
+    live: typeof live;
+    get: typeof get;
+    defaultLive: typeof defaultLive;
+};
+
 declare function setOrigin(url: string): void;
 declare function getOrigin(): string;
+declare function setBearerToken(token: string | null): void;
+declare function getBearerToken(): string | null;
+declare function clearBearerToken(): void;
 declare class MeClientError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
@@ -141,6 +216,22 @@ declare const oc: {
     payment: {
         authorize: (opts: PaymentAuthorizeOptions) => Promise<PaymentResult>;
     };
+    event: {
+        fire: (options: FireEventOptions) => Promise<BillableEvent>;
+    };
+    config: {
+        validate: (cfg: IntegratorPriceConfig) => ValidationResult;
+    };
+    webhook: {
+        verify: typeof verify;
+        fetchJwks: typeof fetchJwksForce;
+    };
+    federations: {
+        list: () => Promise<Federation[]>;
+        live: () => Promise<Federation[]>;
+        get: (slug: string) => Promise<Federation | null>;
+        defaultLive: () => Promise<Federation | null>;
+    };
 };
 
-export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type Session, type SessionPolicy, type SignInOptions, type SiteFeeShape, type TelemetryEvent, type ValidationResult, computeFees, getOrigin, oc, onTelemetry, payment, session, setOrigin, validateIntegratorConfig };
+export { type AttestTier, type BillableEvent, type ClassASubtype, type ClassBSubtype, type ClassCSubtype, type ComputedFees, type EventClass, type EventSubtype, type Federation, type FederationStatus, type FireEventOptions, type IntegratorEventConfig, type IntegratorPriceConfig, MIN_INTEGRATOR_PRICE_SATS, MeClientError, type OcPublicJwk, OcSignInButton, type OcSignInButtonProps, PLATFORM_FEE_POLICY, type PaymentAuthorizeOptions, type PaymentResult, type Session, type SessionPolicy, type SignInOptions, type SigningMethod, type SiteFeeShape, type TelemetryEvent, type ValidationResult, type VerifyOptions, type VerifyResult, clearBearerToken, computeFees, config, event, federations, getBearerToken, getOrigin, oc, onTelemetry, payment, session, setBearerToken, setOrigin, validateIntegratorConfig, webhook };