# Vonvon: full public documentation corpus (en)

- Concise index: https://vonvon.id/en/llms.txt
- Documentation hub: https://vonvon.id/docs
- Published pages: 44

## Canonical aliases

- `/docs/oidc` -> `/oidc-oauth`
- `/docs/oauth` -> `/oidc-oauth`
- `/docs/sso` -> `/enterprise-sso`

## Pages

<!-- vonvon-doc-path: / -->
<!-- vonvon-doc-slug: product -->
# Build identity at the edge, without giving up control

> Vonvon brings Hosted Auth, OIDC, organizations, enterprise federation, directory sync, and SDKs into one MIT-licensed platform running on Cloudflare Workers.

Locale: en
Canonical: https://vonvon.id/
Markdown: https://vonvon.id/index.md
Source: https://vonvon.id/index.mdx

Vonvon brings Hosted Auth, OIDC, organizations, enterprise federation, directory sync, and SDKs into one MIT-licensed platform running on Cloudflare Workers.

## Three focused Workers. One identity platform.

Public content and management stay binding-free. Identity state, protocols, and policy remain in Core.

- **Site:** Product, documentation, search, and agent-readable content
- **Console:** Organization and instance management UI
- **Core:** Hosted Auth, protocols, APIs, data, and asynchronous work

## One control plane from sign-in to enterprise access

Use the complete platform or adopt the protocol, UI, and SDK layers that fit your architecture.

### Authentication and account

Hosted sign-in, passkeys, password, MFA, session management, consent, and account self-service share one tenant-aware Core.

### Organizations and access

Model organizations, OrgUnits, projects, roles, grants, approval policies, and access requests without creating a separate admin tenant.

### Federation and provisioning

Connect inbound SAML and OIDC, downstream SaaS SSO, SCIM, directory sync, and domain discovery behind explicit policy boundaries.

### Protocols and developer experience

Ship OIDC and OAuth flows, Management APIs, webhooks, framework SDKs, localized docs, and networkless token verification from one repository.

## Production where proven, local where not

First-party Hosted Auth, Console, and Management API paths have production evidence on vonvon.id. Enterprise IdP, downstream SaaS, social OAuth, and SMS or WhatsApp claims stay non-production-supported until a real L4 row exists for that path.

## Open source, inspectable, and self-hostable

The MIT-licensed repository includes the complete feature set. Security posture and project governance remain visible through OpenSSF and the public source.

<!-- vonvon-doc-path: /docs -->
# Vonvon Identity Platform

> Vonvon brings Hosted Auth, passkeys, OIDC and OAuth, organizations, enterprise federation, SCIM, and SDKs into one identity platform built for Cloudflare.

Locale: en
Canonical: https://vonvon.id/docs
Markdown: https://vonvon.id/docs/index.md
Source: https://vonvon.id/docs/index.mdx

Open source identity platform

Vonvon brings Hosted Auth, passkeys, OIDC and OAuth, organizations, enterprise federation, SCIM, and SDKs into one identity platform built for Cloudflare.

## One platform for identity

Vonvon handles sign-in, authorization, organization membership, enterprise connections, and user lifecycle from one identity core. Applications use standards-based endpoints while teams manage the instance and every organization from one Console.

Run the same MIT-licensed codebase in single-tenant or multi-tenant mode on your Cloudflare account. Self-hosting includes every feature with no license check or separate edition.

Vonvon is pre-1.0 and not production-ready. The documentation distinguishes local implementation evidence from real provider and SaaS verification.

## What Vonvon includes

- Hosted Auth, passkeys, passwords, magic links, social sign-in, MFA, recovery, consent, and account self-service.
- OIDC and OAuth 2.0, token issuance, discovery, JWKS, organizations, projects, applications, roles, and permissions.
- Inbound enterprise SAML and OIDC, SCIM user and group provisioning, webhooks, audit records, and management APIs.
- Browser, server, web framework, mobile, and desktop SDKs for integrating applications across the stack.

## Explore Vonvon

### Product and setup

- [Getting started](/getting-started)
  Connect an application to Vonvon with OIDC discovery and Hosted Auth.

- [Hosted Auth](/hosted-auth)
  Configure the unified sign-in and user creation flow.

- [Organizations](/organizations)
  Model Organization, OrgUnit, project, and access approval boundaries.

- [Branding](/branding)
  Manage the seven stored organization branding fields exposed by the Management API. Hosted Auth runtime application and custom CSS are not shipped.

- [Self-hosting](/self-hosting)
  Deploy Vonvon as three isolated Workers on your Cloudflare account, with the complete data, queue, consistency, email, routing, and production-control inventory.

### Identity protocols

- [OIDC and OAuth](/oidc-oauth)
  Discovery, authorization, token, logout, and OAuth extension endpoints.

- [Enterprise SSO](/enterprise-sso)
  Configure upstream enterprise IdPs and track downstream SaaS SSO boundaries without overstating production support.

- [Social login](/social-login)
  Configure social OAuth providers while keeping provider-ready separate from production support.

- [SCIM API reference](/scim)
  SCIM 2.0 endpoint contract for provisioning users and groups into Vonvon.

- [SAML SSO](/saml)
  Connect enterprise identity providers using SAML 2.0.

### APIs and operations

- [Management API](/management-api)
  Use scoped API keys to manage organization resources from your backend.

- [Webhooks](/webhooks)
  Subscribe to implemented user, organization, membership, invitation, and SAML certificate events through signed HTTP deliveries.

### SDK overview

- [SDKs](/sdks)
  TypeScript packages and locally verified native SDKs for server, web, mobile, and desktop.

### Server SDKs

- [@vonvon-kit/backend](/sdks/backend)
  Networkless JWT verification, request authentication, and webhook signature validation for edge and server runtimes.

- [sdk/go](/sdks/go)
  Go server SDK for networkless JWT verification, request authentication, and webhook signature validation.

- [sdk/rust](/sdks/rust)
  Async Rust server SDK for networkless JWT verification, request authentication, and webhook signature validation.

- [sdk/python](/sdks/python)
  Async Python server SDK for networkless JWT verification, request authentication, and webhook signature validation.

- [sdk/ruby](/sdks/ruby)
  Ruby server SDK for networkless JWT verification, Rack/Rails request authentication, and webhook signature validation.

- [sdk/php](/sdks/php)
  PHP 8.1+ server SDK for networkless JWT verification, PSR-7 request authentication, and webhook signature validation.

- [sdk/java](/sdks/java)
  Java 17+ server SDK for networkless JWT verification, HTTP request authentication, and webhook signature validation.

- [sdk/dotnet](/sdks/dotnet)
  .NET 8 server SDK for networkless JWT verification, ASP.NET Core request authentication, and webhook signature validation.

### Web SDKs

- [@vonvon-kit/core](/sdks/core)
  Browser client for session state, short-lived JWT access, and Management API helpers.

- [@vonvon-kit/react](/sdks/react)
  React 19 provider, hooks, control components, and hosted UI building blocks for customer applications.

- [@vonvon-kit/nextjs](/sdks/nextjs)
  Next.js middleware, App Router and Pages Router server helpers, plus React SDK re-exports.

- [@vonvon-kit/vue](/sdks/vue)
  Vue 3 plugin, composables, and headless components on top of @vonvon-kit/core.

- [@vonvon-kit/nuxt](/sdks/nuxt)
  Nuxt 3 module with H3/Nitro server middleware and auto-imported Vue composables for SSR and full-stack apps.

- [@vonvon-kit/svelte](/sdks/svelte)
  Svelte 5 reactive stores and SvelteKit server hook for client and SSR authentication.

- [@vonvon-kit/solid](/sdks/solid)
  SolidJS context provider, signal-based auth primitives, and headless components on top of @vonvon-kit/core.

- [@vonvon-kit/angular](/sdks/angular)
  Angular 17+ standalone provider, RxJS service, functional route guards, and standalone components on top of @vonvon-kit/core.

- [@vonvon-kit/astro](/sdks/astro)
  Astro integration with SSR middleware, server helpers, and island client singleton for static and server-rendered Astro sites.

- [@vonvon-kit/remix](/sdks/remix)
  Remix loader and action server helpers, cookie session storage, and OAuth callback handler with React SDK re-exports.

### Mobile SDKs

- [@vonvon-kit/react-native](/sdks/react-native)
  React Native provider and hooks for Hosted Auth redirect, PKCE S256, deep-link callback, and secure token storage adapters.

- [@vonvon-kit/expo](/sdks/expo)
  Expo SecureStore and WebBrowser adapters for @vonvon-kit/react-native plus an Expo Router route guard hook.

- [sdk/ios](/sdks/ios)
  Swift SDK for iOS and macOS using ASWebAuthenticationSession, PKCE S256 authorization code flow, and Keychain token storage.

- [sdk/android](/sdks/android)
  Kotlin SDK for Android using Chrome Custom Tabs, PKCE S256 authorization code flow, and Keystore-backed EncryptedSharedPreferences token storage.

- [sdk/flutter](/sdks/flutter)
  Dart / Flutter SDK for iOS, Android, and desktop using flutter\_web\_auth\_2, PKCE S256 authorization code flow, and flutter\_secure\_storage token persistence.

### Desktop SDKs

- [@vonvon-kit/electron](/sdks/electron)
  Electron SDK with main process PKCE flow, contextBridge preload, OS keychain token storage, and loopback or custom-scheme callback strategies.

- [@vonvon-kit/tauri](/sdks/tauri)
  Tauri v2 desktop SDK with PKCE S256 flow, deeplink callback handler, OS keychain adapter, and Rust plugin template.

- [sdk/macos](/sdks/macos)
  Swift SDK for macOS using ASWebAuthenticationSession, PKCE S256 authorization code flow, and Keychain token storage. Shares the implementation pattern with sdk/ios.

- [sdk/windows](/sdks/windows)
  C# / .NET SDK for WinUI 3 applications using WebView2 for authorization, PKCE S256, and DPAPI-protected IsolatedStorage for token persistence.

- [sdk/linux](/sdks/linux)
  Rust SDK for Linux desktop using xdg-open for browser launch, loopback TCP for the authorization callback, PKCE S256, and freedesktop.org Secret Service token storage.

<!-- vonvon-doc-path: /getting-started -->
<!-- vonvon-doc-slug: getting-started -->
# Getting started

> Connect an application to Vonvon with OIDC discovery and Hosted Auth.

Locale: en
Canonical: https://vonvon.id/getting-started
Markdown: https://vonvon.id/getting-started/index.md
Source: https://vonvon.id/getting-started/index.mdx

## Base URLs

Vonvon is an identity provider. The instance domain is the OIDC issuer, API base URL, Hosted Auth base URL, and console base URL. Organizations provide policy, branding, membership, and resource isolation.

Start by reading `/.well-known/openid-configuration` from the instance domain. The discovery document gives your app the authorization, token, userinfo, logout, and JWKS endpoints for that issuer.

| Surface | Path | Use |
| --- | --- | --- |
| OIDC discovery | `/.well-known/openid-configuration` | Read issuer metadata before configuring a relying party. |
| Authorization | `/authorize` | Redirect users to the unified Hosted Auth flow. |
| Token | `/token` | Exchange an authorization code or refresh token. |
| Userinfo | `/userinfo` | Read claims for a valid access token. |
| Management API | `/v1/*` | Manage organization resources from your backend. |

## Minimum integration

- Create an OIDC application and register exact redirect URI values.
- Use authorization code flow with PKCE S256 for browser and native clients.
- Validate ID tokens and access tokens against the issuer and JWKS URI.
- Store refresh tokens server side or in a secure native credential store.

## Authorization request

```mermaid
sequenceDiagram
  participant Browser
  participant RP
  participant Vonvon
  RP->>Browser: /authorize + PKCE S256
  Browser->>Vonvon: /authorize + PKCE S256
  Vonvon->>Browser: /sign-in
  Browser->>Vonvon: WebAuthn / SSO
  Vonvon->>Browser: code
  Browser->>RP: code
  RP->>Vonvon: /token + PKCE S256
  Vonvon->>RP: ID token + access token
```

```js
const authorizeUrl = new URL('https://vonvon.id/authorize')
authorizeUrl.searchParams.set('client_id', clientId)
authorizeUrl.searchParams.set('redirect_uri', redirectUri)
authorizeUrl.searchParams.set('response_type', 'code')
authorizeUrl.searchParams.set('scope', 'openid profile email')
authorizeUrl.searchParams.set('code_challenge', codeChallenge)
authorizeUrl.searchParams.set('code_challenge_method', 'S256')
```

<!-- vonvon-doc-path: /hosted-auth -->
<!-- vonvon-doc-slug: hosted-auth -->
# Hosted Auth

> Configure the unified sign-in and user creation flow.

Locale: en
Canonical: https://vonvon.id/hosted-auth
Markdown: https://vonvon.id/hosted-auth/index.md
Source: https://vonvon.id/hosted-auth/index.mdx

## Unified flow

Vonvon does not expose separate end-user registration and login products. Hosted Auth starts from the same identifier step and decides login or user creation from organization policy and account state. A guest or credential sign-up with intent=sign-up then creates a top-level Tenant with an Email, Organization name, and URL slug. A guest Email stays pending without reserving an account address; the new owner can read Console data, and verifies that Email before the first business change. The same Email in another Tenant remains a separate account.

Bootstrap defaults enable email magic link and email OTP only. Password, WhatsApp OTP, SMS OTP, passkey, social OAuth, and enterprise SSO stay hidden until the organization policy and required credentials enable them.

Passwordless email magic-link and OTP requests freeze the sign-up intent, server-owned continuation, application client, and invitation row ID when the challenge is created. Social OAuth invitation authorization likewise validates the raw capability before redirecting upstream, persists only the invitation row ID in its one-time state, and ignores caller-owned token routes on callback. Verification cannot rewrite those fields. Raw invitation capabilities are never stored in these flow contexts; when MFA interrupts acceptance, Vonvon uses a short-lived signed continuation bound to the Tenant, User, Session, and invitation.

```mermaid
flowchart TD
  Browser --> authorize["/authorize"]
  authorize --> signIn["/sign-in"]
  signIn --> config["/auth/config"]
  config --> methods["WebAuthn / Password / OTP / SSO"]
  config --> signup["guest or intent=sign-up"]
  signup --> createOrg["/create-organization"]
  createOrg --> readOnly["Console reads"]
  readOnly --> verifyEmail["Verify Email"]
  verifyEmail --> mutations["Business mutations"]
  methods --> code["code"]
  methods --> mfa["/auth/mfa/passkey/*"]
  mfa --> code
```

## Configuration endpoint

`GET /auth/config` returns the public Hosted Auth configuration for the organization. Provider secrets and disabled providers are not returned to the browser.

| Method | Displayed when |
| --- | --- |
| Magic link | Enabled and allowed for login or user creation. |
| Email OTP | Enabled and allowed for login or user creation. |
| Phone OTP | WhatsApp or SMS provider is configured, enabled, and allowed for login or user creation. |
| Password | Password policy enables login or user creation. |
| Social OAuth | Provider is enabled, credentials exist, and policy allows the action. |
| Inbound enterprise SSO | Domain discovery matches a verified organization domain. |

## Identifier policy

- Organizations can require email identifiers, username identifiers, or both.
- Allowed and blocked email domain lists apply before user creation.
- Force SSO hides local methods when an enterprise connection is required.

## WebAuthn and passkey boundaries

- Passkey sign-in is primary AAL2 authentication. Password or OTP sessions can complete MFA through `/auth/mfa/passkey/*` with user verification required.
- Organization policy `attestationMode` selects none, indirect, or direct enterprise attestation during passkey registration.
- WebAuthn credential parameters advertise ES256, RS256, and EdDSA. Syncable passkeys remain AAL2 even after MFA.
- `urn:vonvon:aal3` is not currently issued. WebAuthn UV and BE/BS flags do not prove the non-exportable hardware key required by NIST; AAL3 requests fail explicitly and the current maximum mapping is AAL2.

<!-- vonvon-doc-path: /organizations -->
<!-- vonvon-doc-slug: organizations -->
# Organizations

> Model Organization, OrgUnit, project, and access approval boundaries.

Locale: en
Canonical: https://vonvon.id/organizations
Markdown: https://vonvon.id/organizations/index.md
Source: https://vonvon.id/organizations/index.mdx

## Organization hierarchy

An Instance contains top-level Organizations. An Organization can contain one level of SubOrg; each organization remains a policy, membership, branding, RBAC, and isolation boundary.

An OrgUnit is a department or team inside one Organization. It never changes TenantContext, issuer, token claims, or the one-level SubOrg limit.

- OrgUnit trees support a maximum depth of eight.
- Each member can have one primary OrgUnit and additional placements.
- The nearest active manager in the OrgUnit ancestor chain is the first access-request approver candidate.

## Projects and access policy

Projects group applications and authorization roles. The per-project `access_policy` controls only same-organization users without an effective UserGrant; cross-organization ProjectGrant authorization is unaffected.

| Project policy | Same-organization behavior | Self-service path |
| --- | --- | --- |
| Open | Allowed without a UserGrant. | No access request is needed. |
| Restricted | Denied; an administrator grants access directly. | No self-service request is available. |
| Approval required | Denied until an AccessRequest is approved. | The user submits an access request. |

## Access request lifecycle

AccessRequest moves from `pending` to `approved`, `denied`, `cancelled`, or `expired`. Every outcome is terminal, and pending requests expire lazily after 14 days.

Approval creates a traceable UserGrant in the same transaction. The requester cannot approve their own request; resolution falls through from the OrgUnit manager to project and organization managers.

| Method | Path | Purpose | Required scope |
| --- | --- | --- | --- |
| `GET, POST` | `/auth/access-requests` | Create and list the current user's requests. | `session` |
| `POST` | `/auth/access-requests/:id/cancel` | Cancel the current user's pending request. | `session` |
| `GET` | `/auth/access-approvals` | List requests awaiting the current user's approval. | `session` |
| `POST` | `/auth/access-approvals/:id/{approve\|deny}` | Approve or deny a pending request assigned to the current user. | `session` |
| `GET` | `/v1/organizations/:orgId/access-requests` | List requests inside one organization. | `access-requests:read` |
| `GET` | `/v1/organizations/:orgId/units` | Read the organization unit tree. | `org-units:read` |
| `POST, PATCH, DELETE, PUT` | `/v1/organizations/:orgId/units/*` | Create, update, move, archive, and manage members of units. | `org-units:write` |

## Security boundaries

- Every OrgUnit and AccessRequest query is scoped by `tenant_id` and `org_id`. Cross-organization or cross-tenant identifiers return 404 without revealing existence.
- Membership and project access are separate: invitations join an Organization, while AccessRequest grants an existing active member access to one Project.
- SCIM provisions users and memberships but does not map directory groups to OrgUnits or Project roles in the current implementation.
- The Management API uses cursor pagination and shared API-key or organization-manager guards. It does not reuse end-user business routes.

<!-- vonvon-doc-path: /oidc-oauth -->
<!-- vonvon-doc-slug: oidc-oauth -->
# OIDC and OAuth

> Discovery, authorization, token, logout, and OAuth extension endpoints.

Locale: en
Canonical: https://vonvon.id/oidc-oauth
Markdown: https://vonvon.id/oidc-oauth/index.md
Source: https://vonvon.id/oidc-oauth/index.mdx

## Core endpoints

| Endpoint | Description |
| --- | --- |
| `/.well-known/openid-configuration` | OIDC discovery for the current issuer. |
| `/.well-known/oauth-protected-resource` | OAuth protected resource metadata for Vonvon-hosted resource endpoints. |
| `/jwks` | Instance public signing keys with active and rotating kids. |
| `/authorize` | Authorization endpoint with PKCE, state, nonce, PAR, and Hosted Auth handoff. |
| `/par` | Pushed Authorization Requests with one-time request\_uri values. |
| `/token` | Authorization code, refresh token, client credentials, device code, and token exchange. |
| `/userinfo` | Bearer or DPoP access token user claims. |
| `/end_session` | RP-initiated logout with registered post logout redirects. |

## Protocol requirements

- PKCE uses S256. Plain PKCE is rejected.
- Redirect URI matching is exact. Wildcards are not accepted.
- Authorization codes are one-time use.
- Refresh tokens rotate on every use and replay revokes the token family.
- DPoP-bound clients must present a valid DPoP proof for token and resource calls. Authorization request `dpop_jkt` is bound to authorization code exchange.

## Support levels

| Level | OAuth and OIDC features |
| --- | --- |
| Implemented | Authorization code, PKCE S256, refresh rotation, PAR, DPoP proof and `dpop_jkt` binding, dynamic client registration, ID tokens, userinfo, hybrid response types, signed JAR request objects, signed JARM responses, RAR `resource_access` authorization details, token exchange, mTLS client authentication, front-channel and back-channel logout, Device Flow, Session Management, CIBA, Browser-Based Apps profile gates, and FAPI 2.0 profile gates. |
| Minimal implementation | OpenID Federation exposes entity metadata and a registration boundary only. Trust-chain resolution, trust anchors, policy processing, and production interoperability are not implemented. |
| Planned | Shared Signals, CAEP, RISC, GNAP, UMA, HEART, OpenID4VP, and OpenID4VCI expose reserved routes that return explicit 501 errors. They are not protocol implementations. |
| Production evidence | Local implementation and conformance gates are not production certification. Downstream SaaS OIDC uses the generic OIDC baseline, but each SaaS integration still requires real external L4 evidence. |
| Deprecated or not supported | Implicit flow, password grant, plain PKCE, and wildcard redirects. |

## Role boundaries

| Vonvon role | Current public status |
| --- | --- |
| OIDC / OAuth identity provider for customer applications | Implemented in local and Worker routes with authorization code, PKCE S256, PAR, DPoP, JAR, JARM, RAR, discovery, JWKS, token, userinfo, introspection, and revocation coverage. |
| Upstream enterprise OIDC relying party | Provider-ready for enterprise connections. Production support requires a real IdP configuration and callback L4. |
| Social OAuth relying party | Provider-ready for GitHub, Google, Microsoft account, and Apple. See Social login for provider-specific boundaries. |
| Downstream SaaS OIDC identity provider | Generic OIDC baseline is available locally. SaaS-specific app templates and real SaaS L4 are still required before production support claims. |

## Client types

| Client | Recommended flow |
| --- | --- |
| Web application | Authorization code with server side token exchange. |
| SPA | Authorization code with PKCE S256. |
| Native app | Authorization code with PKCE S256 and claimed redirects. |
| Machine to machine | Client credentials with scoped access. |

## Guarded or minimal OAuth and OIDC extensions

| Level | Status |
| --- | --- |
| Assertion grants | JWT bearer and SAML bearer assertion grants are not enabled. Registration rejects assertion grant metadata until a trust root exists. |
| GNAP, UMA, HEART, OpenID4VP, OpenID4VCI | Only negative route and metadata stubs are exposed. Unsupported operations return explicit `501 unsupported_feature`; no functional protocol support is claimed. |

<!-- vonvon-doc-path: /enterprise-sso -->
<!-- vonvon-doc-slug: enterprise-sso -->
# Enterprise SSO

> Configure upstream enterprise IdPs and track downstream SaaS SSO boundaries without overstating production support.

Locale: en
Canonical: https://vonvon.id/enterprise-sso
Markdown: https://vonvon.id/enterprise-sso/index.md
Source: https://vonvon.id/enterprise-sso/index.mdx

## Two directions

Inbound enterprise SSO means Vonvon acts as the SAML service provider or OIDC relying party for a company IdP. Downstream SaaS SSO means Vonvon acts as the SAML or OIDC identity provider for apps such as Slack, GitHub Enterprise Cloud, Microsoft custom apps, Atlassian, Salesforce, and Zoom.

Both directions are separate evidence lines. A local fake IdP or fake SaaS run verifies the implementation baseline, but only a real external IdP or SaaS admin run can support a production-supported claim.

```mermaid
flowchart LR
  IdP -->|SAML / OIDC| vonvonSp["Vonvon SP / RP"]
  vonvonIdP["Vonvon IdP"] -->|SAML / OIDC| SaaS
```

## Upstream enterprise IdP status

| Provider | Protocols | Status |
| --- | --- | --- |
| Microsoft Entra ID | SAML, OIDC, SCIM inbound | Provider-ready, missing real IdP L4. |
| Okta | SAML, OIDC, SCIM inbound | Provider-ready, missing real IdP L4. |
| Google Workspace | SAML, OIDC, SCIM inbound | Provider-ready, missing real IdP L4. |
| OneLogin | SAML, OIDC, SCIM inbound | Provider-ready, missing real IdP L4. |
| JumpCloud | SAML, OIDC, SCIM inbound | Provider-ready, missing real IdP L4. |
| PingOne | SAML, OIDC | Provider-ready, missing real IdP L4. |
| PingFederate | SAML, OIDC | Provider-ready, missing real IdP L4. |
| AD FS | SAML, OIDC, WS-Fed legacy baseline | Implemented locally; real AD FS WS-Fed L4 missing. |
| Shibboleth | SAML, OIDC | Provider-ready, missing real IdP L4. |
| Keycloak | SAML, OIDC, LDAP legacy baseline | Implemented locally; native Kerberos bridge is documented-only. |

## Downstream SaaS SSO status

| SaaS | Direction | Status |
| --- | --- | --- |
| Slack | Vonvon as SAML IdP | Provider-ready with local outbound SAML baseline; real Slack admin L4 missing. |
| GitHub Enterprise Cloud | Vonvon as SAML IdP | Provider-ready with local outbound SAML baseline; real GitHub Enterprise L4 missing. |
| Microsoft custom enterprise app | Vonvon as SAML or OIDC IdP | Provider-ready with generic SAML/OIDC baseline; real Entra custom app L4 missing. |
| Atlassian | Vonvon as SAML IdP | Provider-ready with local outbound SAML baseline; real Atlassian admin L4 missing. |
| Salesforce | Vonvon as SAML or OIDC IdP | Provider-ready with generic SAML/OIDC baseline; real Salesforce admin L4 missing. |
| Zoom | Vonvon as SAML or OIDC IdP | Provider-ready with generic SAML/OIDC baseline; real Zoom admin L4 missing. |

## Legacy protocol boundaries

- LDAP direct bind, WS-Federation, SWA password vaulting, header-based SSO, and directory connector framework are implemented locally with fake harness L3. Real AD/LDAP gateway, AD FS WS-Fed, target app vault, and Application Proxy L4 are still missing.
- Linked sign-on, native IWA, and Kerberos termination are not supported.
- SAML Single Logout is implemented and verified locally at L1/L2 for inbound and outbound SAML. The Slack profile is excluded because Slack does not support SLO; real IdP and downstream SaaS L4 evidence remains UNKNOWN.
- Provider-ready rows must not be described as production-supported until real external L4 evidence exists.

<!-- vonvon-doc-path: /social-login -->
<!-- vonvon-doc-slug: social-login -->
# Social login

> Configure social OAuth providers while keeping provider-ready separate from production support.

Locale: en
Canonical: https://vonvon.id/social-login
Markdown: https://vonvon.id/social-login/index.md
Source: https://vonvon.id/social-login/index.mdx

## Provider status

Social login is provider-ready until real provider callback L4 exists. Vonvon has local callback, profile mapping, nonce, policy, and organization gate coverage, but real provider secrets and callbacks are required before production-supported claims.

| Provider | Protocol | Status |
| --- | --- | --- |
| GitHub | OAuth authorization code | Provider-ready, missing real GitHub callback L4. |
| Google | OIDC authorization code | Provider-ready, missing real Google callback L4. |
| Microsoft account | OIDC authorization code | Provider-ready, separate from Microsoft Entra ID. |
| Apple | Sign in with Apple | Provider-ready, missing real Apple web configuration and callback L4. |

## Configuration contract

- Provider credentials are stored as secret references and are never returned to the browser.
- Hosted Auth only displays enabled providers that have credentials and organization policy permission.
- Callbacks verify state, nonce, issuer, audience, and email policy before creating or linking users.
- GitHub social login is separate from GitHub Enterprise Cloud SAML or SCIM.
- Microsoft account login is separate from Microsoft Entra ID enterprise SSO.

<!-- vonvon-doc-path: /management-api -->
<!-- vonvon-doc-slug: management-api -->
# Management API

> Use scoped API keys to manage organization resources from your backend.

Locale: en
Canonical: https://vonvon.id/management-api
Markdown: https://vonvon.id/management-api/index.md
Source: https://vonvon.id/management-api/index.mdx

## Authentication

Management API calls use `Authorization: Bearer sk_live_*` or `Authorization: Bearer sk_test_*`. Keys are scoped to the resolved Tenant. Organization resources additionally verify that the requested Organization belongs to that Tenant.

```shell
curl https://vonvon.id/v1/users \
  -H 'Authorization: Bearer sk_live_xxx'
```

## Resources

| Resource | Capabilities | Status |
| --- | --- | --- |
| `/v1/users` | Create, read, update, ban, unban, export, and remove users. | Implemented |
| `/v1/organizations` | Manage organizations, domains, branding, and settings. | Implemented |
| `/v1/organizations/:orgId/memberships` | List, create, update role, and remove members. | Implemented |
| `/v1/organizations/:orgId/invitations` | Create (with bulk limit), revoke, and list invitations. | Implemented |
| `/v1/sessions` | List, get, and revoke user sessions. | Implemented |
| `/v1/applications` | Register OAuth clients, redirect URIs, grants, token policy, and secrets. | Implemented |
| `/v1/connections` | Manage upstream enterprise SSO connections. | Implemented |
| `/v1/directories` | Create SCIM directories and rotate directory tokens. | Implemented |
| `/v1/roles` | Create, read, update, and delete custom roles. | Implemented |
| `/v1/permissions` | Create, read, update, and delete permissions. | Implemented |
| `/v1/project-grants` | Create, list, get, revoke, and delete project grants. | Implemented |
| `/v1/user-grants` | Assign, list, get, revoke, and delete scoped user grants. | Implemented |
| `/v1/organizations/:orgId/domains` | List, create, and remove organization domains. | Implemented |
| `/v1/organizations/:orgId/custom-hostnames` | Create, inspect, refresh, and remove custom hostnames. | Implemented |
| `/v1/organizations/:orgId/audit-events` | Read organization audit events with cursor pagination. | Implemented |
| `/v1/webhooks` | Create, list, update, and delete webhook endpoints. | Implemented |
| `/v1/api-keys` | Create, list, and revoke organization API keys. | Implemented |
| `/v1/organizations/:orgId/scim-targets` | Create, update, sync, and remove outbound SCIM targets. | Implemented |

## Pagination and errors

List endpoints return a data array and cursor metadata. Errors use structured JSON with a stable code, a human-readable message, and optional metadata for field validation.

<!-- vonvon-doc-path: /webhooks -->
<!-- vonvon-doc-slug: webhooks -->
# Webhooks

> Subscribe to implemented user, organization, membership, invitation, and SAML certificate events through signed HTTP deliveries.

Locale: en
Canonical: https://vonvon.id/webhooks
Markdown: https://vonvon.id/webhooks/index.md
Source: https://vonvon.id/webhooks/index.mdx

## Event naming

Implemented events follow the pattern `<object>.<action>`. The vonvon-webhook-event header and body type carry the exact event name; every delivery also has a unique `svix-id`.

| Object | Actions |
| --- | --- |
| `user` | created, updated, deleted, restored, banned, unbanned, deactivated |
| `organization` | created, updated, deleted, restored |
| `organization.auth_policy` | updated |
| `organization.delivery_channels` | updated |
| `organization.social_providers` | updated |
| `organization.outbound_saml_app` | created, deleted |
| `organization.scim_target` | created, deleted |
| `organizationMembership` | created, updated, deleted, restored |
| `organizationInvitation` | created, accepted, revoked |
| `connection` | saml\_certificate\_renewed |
| `user.*` | Subscription wildcard for all implemented user events. |
| `organization.*` | Subscription wildcard for all implemented organization events, including dotted sub-events. |
| `organizationMembership.*` | Subscription wildcard for all implemented organization membership events. |
| `*` | Subscription wildcard for every implemented event. |

## Payload structure

Every webhook delivery is an HTTP POST with `Content-Type: application/json`. The body contains the exact event `type` and its `data`; svix metadata is carried in request headers.

```json
{
  "type": "user.created",
  "data": {
"userId": "user_01abc"
  }
}
```

## Signature verification

Vonvon signs every delivery with HMAC-SHA256. Verify the signature before processing the payload. Reject deliveries older than 5 minutes to prevent replay attacks.

| Header | Description |
| --- | --- |
| `svix-id` | Unique message ID. Use this to deduplicate retried deliveries. |
| `svix-timestamp` | Unix seconds when the message was sent. |
| `svix-signature` | The svix-signature header starts with the literal v1, prefix, followed by the Base64-encoded HMAC-SHA256 of `${svix-id}.${svix-timestamp}.${raw-body}` using the endpoint signing secret. |

```ts
import { verifyWebhook } from '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_WEBHOOK_SECRET,
})
if (!result.ok) {
  return new Response('Invalid webhook', { status: 400 })
}
const { type, data } = result.value.payload
```

## Retries and dead letters

- Delivery attempts use exponential backoff and end in dead status. Queue-level exhaustion is persisted as an encrypted dead-letter record for Instance Manager inspection and replay.
- Delivery is decoupled from the authentication path through Cloudflare Queues. A slow or unavailable endpoint does not affect login latency.
- Use the `svix-id` header to deduplicate deliveries on your end. Retries carry the same `svix-id` as the original attempt.

```mermaid
flowchart LR
  Vonvon --> Queue
  Queue -->|HTTPS| Endpoint
  Endpoint -->|2xx| ACK
  Endpoint -->|non-2xx| Retry
  Retry --> Queue
  Retry -->|max_retries| dlq["D1 DLQ"]
```

## Endpoint recovery

Use `POST /v1/webhooks/:id/restore` to reactivate a deleted endpoint and `POST /v1/webhooks/:id/rotate-secret` to replace its signing secret. The new `signing_secret` is returned once. Product-level replay by delivery ID or `time range` is not implemented.

```shell
curl -X POST https://vonvon.id/v1/webhooks/webhook_xxx/rotate-secret \
  -H 'Authorization: Bearer sk_live_xxx'
```

## Delivery history boundary

Vonvon does not expose a pull Events API. Use `GET /v1/webhooks` to manage subscriptions; delivery state and queue dead-letter replay are operational surfaces for Instance Managers, not a tenant event stream.

```shell
curl 'https://vonvon.id/v1/webhooks?limit=100' \
  -H 'Authorization: Bearer sk_live_xxx'
```

<!-- vonvon-doc-path: /branding -->
<!-- vonvon-doc-slug: branding -->
# Branding

> Manage the seven stored organization branding fields exposed by the Management API. Hosted Auth runtime application and custom CSS are not shipped.

Locale: en
Canonical: https://vonvon.id/branding
Markdown: https://vonvon.id/branding/index.md
Source: https://vonvon.id/branding/index.mdx

## Branding options

The Management API stores seven organization-scoped branding values in KV. They are available to authenticated management clients; automatic Hosted Auth and email rendering is not implemented.

| Option | Description |
| --- | --- |
| Primary color | Stored primary color value for management clients. |
| Background color | Stored page background value for management clients. |
| Accent color | Stored accent color value for management clients. |
| Border radius | Stored border-radius value. The API does not constrain it to a named scale. |
| Font family | Stored font-family value. The API does not fetch or validate remote fonts. |
| Logo (light) | Stored light-theme logo URL. Uploading an organization logo is a separate R2-backed endpoint. |
| Logo (dark) | Stored dark-theme logo URL; this API does not apply an automatic fallback. |

## Per-organization branding

Each record is keyed by tenant and organization in KV. Reads return all seven fields with null values when no record exists; no runtime rendering or latency guarantee is implied.

## Management API endpoint

Update organization branding with a PATCH request using camelCase field names. Omitted fields and `null` currently retain the stored value; send a replacement string to change a field.

```shell
curl -X PATCH https://vonvon.id/v1/organizations/org_xxx/branding \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
"primaryColor": "#6366f1",
"borderRadius": "0.5rem",
"fontFamily": "Inter, sans-serif",
"logoUrl": "https://cdn.example.com/logo.svg"
  }'
```

## Validation boundary

- The branding schema accepts only the seven fields listed above; custom CSS is not accepted.
- `@import` and `url()` CSS processing is not implemented because the endpoint accepts no stylesheet.
- Values are stored as strings; color, radius, font, and URL syntax are not validated beyond JSON types.
- Iframe preview and separate draft and published states are not implemented.

## Email template boundary

Transactional email uses built-in Mustache templates and global R2 locale packs. Per-organization HTML template upload and automatic branding injection are not implemented.

<!-- vonvon-doc-path: /scim -->
<!-- vonvon-doc-slug: scim -->
# SCIM API reference

> SCIM 2.0 endpoint contract for provisioning users and groups into Vonvon.

Locale: en
Canonical: https://vonvon.id/scim
Markdown: https://vonvon.id/scim/index.md
Source: https://vonvon.id/scim/index.mdx

## Base URL

Vonvon exposes organization-scoped SCIM 2.0 APIs under `/scim/v2/organizations/{organization_id}`. User and group resources are addressed with the organization ID in the path.

Configure your identity provider with the base URL `https://vonvon.id/scim/v2/organizations/{organization_id}` and the directory token shown once when you create or rotate the directory.

```shell
curl https://vonvon.id/scim/v2/organizations/{organization_id}/Users \
  -H 'Authorization: Bearer scim_xxx' \
  -H 'Content-Type: application/scim+json'
```

## Authentication

SCIM calls use a directory bearer token created from the Management API. Vonvon stores only a hash of the token and returns the plaintext token once when it is created or rotated.

| Header | Value | Notes |
| --- | --- | --- |
| `Authorization` | `Bearer scim_xxx` | Required for organization-scoped user and group endpoints. |
| `Content-Type` | `application/scim+json` | Required for POST, PUT, and PATCH requests. |
| `Accept` | `application/scim+json` | Recommended for all SCIM clients. |

## Endpoints

| Endpoint | Methods | Use |
| --- | --- | --- |
| `/scim/v2/ServiceProviderConfig` | `GET` | ServiceProviderConfig response for SCIM client discovery. |
| `/scim/v2/Schemas` | `GET` | User and Group schema metadata. |
| `/scim/v2/ResourceTypes` | `GET` | Supported SCIM resource types. |
| `/scim/v2/organizations/{organization_id}/Users` | `GET, POST` | Create and list directory users. |
| `/scim/v2/organizations/{organization_id}/Users/{id}` | `GET, PUT, PATCH, DELETE` | Read, replace, patch, or deprovision one directory user. |
| `/scim/v2/organizations/{organization_id}/Groups` | `GET, POST` | Create and list directory groups. |
| `/scim/v2/organizations/{organization_id}/Groups/{id}` | `GET, PUT, PATCH, DELETE` | Read, replace, patch, or remove one directory group. |

## User resource

User resources use `userName` as the external identifier. Email values, profile name fields, active state, and enterprise extension fields are preserved in the SCIM raw profile.

| SCIM field | Vonvon behavior |
| --- | --- |
| `id` | Stable Vonvon directory user ID. |
| `userName` | Required. Must be unique inside the directory. |
| `active` | `false` deprovisions the user and revokes active sessions. |
| `emails` | Primary email is used for matching and account linking. |
| `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` | Stored and returned for enterprise attributes such as department. |

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "alice@example.com",
  "active": true,
  "name": { "givenName": "Alice", "familyName": "Lee" },
  "emails": [{ "value": "alice@example.com", "primary": true }]
}
```

## Group resource

Group resources use `displayName` as the unique directory group name. Members reference SCIM user IDs and are synchronized idempotently.

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
{ "value": "dir_user_123", "display": "alice@example.com" }
  ]
}
```

## Filtering, sorting, and pagination

Vonvon supports SCIM filter grammar with `and`, `or`, `not`, and comparison operators (`eq`, `ne`, `co`, `sw`, `ew`, `gt`, `ge`, `lt`, `le`, `pr`). Unsupported expressions return `invalidFilter`. List responses use SCIM 1-based pagination with `startIndex`, `count`, and `totalResults`, plus optional `sortBy` and `sortOrder`.

| Query | Support |
| --- | --- |
| `filter=userName eq "alice@example.com"` | Find one user by userName. |
| `filter=displayName eq "Engineering"` | Find one group by displayName. |
| `filter=userName sw "alice" and active eq true` | Combine logical and comparison operators. |
| `sortBy=userName&sortOrder=ascending` | Sort Users or Groups list results. |
| `startIndex=1&count=100` | Return up to 100 resources from the first result. |
| `attributes=userName,emails.value` | Return only schemas, id, and the requested SCIM attributes. |
| `excludedAttributes=emails,meta` | Return the default resource without the excluded SCIM attributes. |

## Bulk operations

`POST /scim/v2/organizations/{organization_id}/Bulk` accepts a `BulkRequest` with up to 100 operations and a 1 MiB payload limit. Responses return per-operation HTTP status in a `BulkResponse` even when some operations fail.

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
{
  "method": "POST",
  "path": "/Users",
  "bulkId": "user1",
  "data": { "userName": "alice@example.com", "active": true }
}
  ]
}
```

## ETag and If-Match

Resource GET responses include `ETag: W/"<meta.version>"` from `meta.version`. `PUT` and `PATCH` require an `If-Match` header matching the current version; missing headers return `428` and mismatches return `412`.

## PATCH operations

PATCH requests use `urn:ietf:params:scim:api:messages:2.0:PatchOp`. Vonvon supports `add`, `replace`, and `remove` for writable profile fields and group memberships.

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
{ "op": "replace", "path": "active", "value": false }
  ]
}
```

## Error responses

SCIM errors return `application/scim+json` with the SCIM Error schema, HTTP status, detail, and optional `scimType`.

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "userName already exists"
}
```

## ServiceProviderConfig capabilities

- `ServiceProviderConfig` advertises `sort.supported=true`, `bulk.supported=true`, and `etag.supported=true`.
- Vonvon exposes inbound SCIM Service Provider endpoints for external IdPs. Downstream SaaS SCIM push clients have local fake-SaaS evidence, but production support still requires real SaaS admin L4.

## Deprovisioning behavior

- Directory token rotation keeps the previous token valid for a short grace window.
- `active=false` and `DELETE /Users/{id}` deprovision the user and revoke active sessions.
- Group membership updates are idempotent. Unknown members can be resolved after the user arrives from the identity provider.

<!-- vonvon-doc-path: /saml -->
<!-- vonvon-doc-slug: saml -->
# SAML SSO

> Connect enterprise identity providers using SAML 2.0.

Locale: en
Canonical: https://vonvon.id/saml
Markdown: https://vonvon.id/saml/index.md
Source: https://vonvon.id/saml/index.mdx

## Service provider endpoints

| Endpoint | Description |
| --- | --- |
| `/sso/hrd` | Find the enterprise connection for a verified email domain. |
| `/sso/saml/{connection}/metadata` | SP metadata XML for the configured connection. |
| `/sso/saml/{connection}/login` | SP-initiated AuthnRequest redirect to the IdP. |
| `/sso/saml/{connection}/acs` | ACS endpoint for signed or encrypted SAML responses. |

## Security model

SAML is provider-ready: local and fake-IdP evidence covers the current Worker routes, and production readiness still requires a real IdP connection without recording SAMLResponse values or provider secrets.

- IdP certificates are stored on the connection. Browser-supplied KeyInfo is ignored.
- Assertions are validated for issuer, audience, recipient, time window, InResponseTo, and replay.
- EncryptedAssertion uses the configured SP decrypt key, then still requires the decrypted assertion signature to verify.
- XML security prechecks, a recursive structural schema allowlist, and the signature/reference structure allowlist are implemented and verified locally. The structural allowlist validates the SAML Response before signature verification and each decrypted Assertion again; it is a closed grammar for the consumed SAML profile, not a general XSD engine. Inbound and outbound SAML Single Logout is covered locally at L1/L2. The Slack profile is excluded because Slack does not support SLO, and real provider L4 evidence remains UNKNOWN.
- Vonvon currently acts as the SAML service provider for enterprise IdPs. Outbound SAML IdP for downstream SaaS apps has local fake-SaaS evidence, but production support still requires real SaaS admin L4.
- JIT provisioning can create or update users when the connection policy allows it.
- SCIM remains the recommended source for deprovisioning and group membership lifecycle.

<!-- vonvon-doc-path: /sdks -->
<!-- vonvon-doc-slug: sdks -->
# SDKs

> TypeScript packages and locally verified native SDKs for server, web, mobile, and desktop.

Locale: en
Canonical: https://vonvon.id/sdks
Markdown: https://vonvon.id/sdks/index.md
Source: https://vonvon.id/sdks/index.mdx

## Status legend

Every SDK below carries one of two status labels, aligned with the Vonvon platform support matrix. Neither label is a production-readiness claim.

| Status | Meaning |
| --- | --- |
| Current package | TypeScript package maintained in the Vonvon repository with source, tests, and workspace wiring. |
| Implemented and verified locally | Native SDK that compiles and passes its unit test suite on a local toolchain. A round-trip against a real production IdP still requires manual verification. |

## Server-side SDKs

Web-standard runtimes (Cloudflare Workers, Node.js, Bun, Deno) share @vonvon-kit/backend via Web Crypto. Other languages get native SDKs. All do networkless JWT verification, request authentication, and webhook verification.

| Runtime or language | Package or directory | Status | Responsibility |
| --- | --- | --- | --- |
| Cloudflare Workers | `@vonvon-kit/backend` | Current package | Networkless JWT verification, request authentication, and webhook verification. |
| Node.js | `@vonvon-kit/backend` | Current package | Networkless JWT verification, request authentication, and webhook verification. |
| Bun | `@vonvon-kit/backend` | Current package | Networkless JWT verification, request authentication, and webhook verification. |
| Deno | `@vonvon-kit/backend` | Current package | Networkless JWT verification, request authentication, and webhook verification. |
| Go | `sdk/go` | Implemented and verified locally | Networkless JWT verification, request authentication, and webhook verification. |
| Java | `sdk/java` | Implemented and verified locally | Networkless JWT verification, request authentication, and webhook verification. |
| Rust | `sdk/rust` | Implemented and verified locally | Networkless JWT verification, request authentication, and webhook verification. |
| PHP | `sdk/php` | Implemented and verified locally | Networkless JWT verification, request authentication, and webhook verification. |
| Ruby | `sdk/ruby` | Implemented and verified locally | Networkless JWT verification, request authentication, and webhook verification. |
| Python | `sdk/python` | Implemented and verified locally | Networkless JWT verification, request authentication, and webhook verification. |
| .NET | `sdk/dotnet` | Implemented and verified locally | Networkless JWT verification, request authentication, and webhook verification. |

## Client SDKs: web frameworks

| Framework | Package or directory | Status | Responsibility |
| --- | --- | --- | --- |
| Vanilla JS / Web | `@vonvon-kit/core` | Current package | Browser client, session store, token cache, and Management API helpers. |
| React | `@vonvon-kit/react` | Current package | Provider, hooks, control components, user UI, and organization UI. |
| Next.js | `@vonvon-kit/nextjs` | Current package | Middleware, App Router helpers, Pages Router helpers, and React re-exports. |
| Vue | `@vonvon-kit/vue` | Current package | Provider, hooks or composables, and prebuilt user and organization components. |
| Nuxt | `@vonvon-kit/nuxt` | Current package | Provider, hooks or composables, and prebuilt user and organization components. |
| Svelte / SvelteKit | `@vonvon-kit/svelte` | Current package | Provider, hooks or composables, and prebuilt user and organization components. |
| Angular | `@vonvon-kit/angular` | Current package | Provider, hooks or composables, and prebuilt user and organization components. |
| Remix | `@vonvon-kit/remix` | Current package | Provider, hooks or composables, and prebuilt user and organization components. |
| Astro | `@vonvon-kit/astro` | Current package | Provider, hooks or composables, and prebuilt user and organization components. |
| SolidJS | `@vonvon-kit/solid` | Current package | Provider, hooks or composables, and prebuilt user and organization components. |

## Client SDKs: mobile

| Platform | Package or directory | Status | Responsibility |
| --- | --- | --- | --- |
| React Native | `@vonvon-kit/react-native` | Current package | Hosted redirect, deep link callback, PKCE S256, and secure storage adapter contract. |
| Expo | `@vonvon-kit/expo` | Current package | Expo Router integration, AuthSession, and SecureStore adapter. |
| Flutter | `sdk/flutter` | Implemented and verified locally | Hosted redirect, app link callback, and secure storage adapter. |
| iOS | `sdk/ios` | Implemented and verified locally | ASWebAuthenticationSession, Keychain storage, and PKCE S256. |
| Android | `sdk/android` | Implemented and verified locally | Custom Tabs, App Links, Keystore-backed storage, and PKCE S256. |

## Client SDKs: desktop

| Platform | Package or directory | Status | Responsibility |
| --- | --- | --- | --- |
| macOS | `sdk/macos` | Implemented and verified locally | ASWebAuthenticationSession, Keychain storage, and PKCE S256. |
| Windows | `sdk/windows` | Implemented and verified locally | WebView2 redirect, DPAPI secure storage, and PKCE S256. |
| Linux | `sdk/linux` | Implemented and verified locally | System browser redirect, Secret Service storage, and PKCE S256. |
| Electron | `@vonvon-kit/electron` | Current package | Main and renderer bridge, safeStorage, and loopback or custom scheme callbacks. |
| Tauri | `@vonvon-kit/tauri` | Current package | Rust backend bridge, OS keychain, and PKCE S256. |

## Shared native contract

- Native public clients use authorization code with PKCE S256. Implicit flow and password grant are not supported.
- Redirect callbacks are claimed app links, universal links, custom schemes, or platform equivalent callback URLs.
- Storage adapters keep refresh tokens or session cache values in platform secure storage and never store client secrets.
- JS and TS native SDKs (React Native, Expo) use a React provider plus hooks model: VonvonProvider, useSignIn, and useSignOut.
- Other native SDKs (iOS, Android, Flutter, desktop) use a functional configure, signIn, and handleRedirect API surface.

## Package guides

Each SDK has a dedicated reference page with install steps, API tables, and copy-paste examples. The SDK packages group in the sidebar lists every reference page; the most used web packages are:

- [@vonvon-kit/core](/sdks/core) — browser session, tokens, Management API helpers.
- [@vonvon-kit/backend](/sdks/backend) — networkless JWT verify, request auth, webhooks.
- [@vonvon-kit/react](/sdks/react) — provider, hooks, control and UI components.
- [@vonvon-kit/nextjs](/sdks/nextjs) — middleware and App/Pages Router server helpers.
- [@vonvon-kit/react-native](/sdks/react-native) — Hosted Auth redirect, PKCE S256, secure token storage for native apps.

<!-- vonvon-doc-path: /sdks/core -->
<!-- vonvon-doc-slug: sdks/core -->
# @vonvon-kit/core

> Browser client for session state, short-lived JWT access, and Management API helpers.

Locale: en
Canonical: https://vonvon.id/sdks/core
Markdown: https://vonvon.id/sdks/core/index.md
Source: https://vonvon.id/sdks/core/index.mdx

## Install and configure

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

For a developer app on another origin, configure `mode: 'oidc'` with issuer, clientId, and an exact redirectUri. Use same-origin mode only when the application routes Core auth endpoints on its exact origin. Vonvon has no publishable-key credential.

```ts
import { VonvonClient } from '@vonvon-kit/core'

const vonvon = new VonvonClient({
  mode: 'oidc',
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
})

const authorization = await vonvon.createAuthorizationUrl({ returnUrl: '/dashboard' })
if (!authorization.ok) throw new Error(authorization.error.message)
window.location.assign(authorization.value)
```

## Session lifecycle

- `load()` reads `/v1/me` and hydrates user, session, and active organization.
- `signInPassword()` establishes a cookie session through Hosted Auth password flow.
- `getToken()` returns a short-lived JWT for API calls. Verify networklessly on your backend with JWKS.
- `setActiveOrganization()` switches org context and clears the token cache before reloading state.
- `signOut()` revokes the browser session cookie.

## Management API helpers

Management API helpers are `server-side or exact same-origin only`. Construct a separate client with `sk_live_*` or sk\_test\_\* on the server; OIDC browser mode rejects these operations.

```ts
const management = new VonvonClient({
  apiUrl: 'https://vonvon.id',
  secretKey: process.env.VONVON_SECRET_KEY,
})

const keys = await management.listApiKeys()
if (!keys.ok) throw new Error(keys.error.message)

const created = await management.createApiKey({ name: 'CI deploy', scopes: ['read'] })
if (!created.ok) throw new Error(created.error.message)

const revoked = await management.revokeApiKey({ id: created.value.id })
if (!revoked.ok) throw new Error(revoked.error.message)
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `VonvonClient` | class | Top-level browser client: load, signIn, getToken, setActiveOrganization, signOut, and Management API helpers |
| `VonvonStore` | class | Framework-agnostic reactive store; subscribe with useSyncExternalStore in framework bindings |
| `TokenManager` | class | Short-lived JWT cache and scheduled refresh (advanced use and testing) |
| `VonvonApiClient` | class | HTTP client for /v1/me and token endpoints |
| `VonvonNetworkError` | class | Thrown on transport failures: network error, non-JSON response, 5xx with no structured body |
| `makeVonvonError` | function | Construct a structured VonvonError for local validation failures without a network round-trip |
| `isVonvonErrorShape` | function | Type guard: checks whether an unknown value conforms to VonvonError shape from the wire |
| `decodeTokenClaims` | function | Decode JWT payload claims for expiry scheduling only; does not verify the signature |
| `isTokenExpiring` | function | Returns true when the token expires within the leeway window (default 10 s) |
| `SESSION_STATUS` | as const tuple | Valid session status values: active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | as const tuple | Valid client status values: loading, ready, degraded, error |
| `PACKAGE` | string constant | Package name identifier '@vonvon-kit/core' |

## Types

| Type | Description |
| --- | --- |
| `VonvonUser` | Read-only view of the authenticated user (no secrets or hashes) |
| `VonvonOrganization` | Public organization view |
| `VonvonOrganizationMembership` | User membership in an org with role and permissions |
| `VonvonSession` | Session view including status, expiry, and active org |
| `VonvonApiKey` | API key without secret (list view) |
| `VonvonApiKeyWithSecret` | API key returned once at creation; includes the key field |
| `VonvonPage<T>` | Cursor-paginated response envelope |
| `CreateApiKeyInput` | Input for createApiKey |
| `SignInPasswordInput` | Input for signInPassword |
| `SignInResult` | Result from signInPassword: next step or redirect URL |
| `SessionStatus` | Union of SESSION\_STATUS values |
| `ClientStatus` | Union of CLIENT\_STATUS values |
| `VonvonState` | Full SDK state snapshot subscribed from VonvonStore |
| `VonvonStateListener` | State change listener callback type |
| `Unsubscribe` | Return type of VonvonStore.subscribe |
| `GetTokenOptions` | Options for getToken: skipCache, leewaySeconds, signal |
| `VonvonClientOptions` | Discriminated VonvonClient constructor options: same-origin accepts apiUrl, secretKey, fetcher, and now; oidc requires issuer, clientId, and redirectUri. |
| `TokenResponse` | Raw token endpoint response shape |
| `ClientStateResponse` | Raw /v1/me response shape |
| `DecodedTokenClaims` | JWT payload claims returned by decodeTokenClaims |

## Related docs

Framework bindings: [@vonvon-kit/react](/sdks/react). Server verification: [@vonvon-kit/backend](/sdks/backend).

<!-- vonvon-doc-path: /sdks/backend -->
<!-- vonvon-doc-slug: sdks/backend -->
# @vonvon-kit/backend

> Networkless JWT verification, request authentication, and webhook signature validation for edge and server runtimes.

Locale: en
Canonical: https://vonvon.id/sdks/backend
Markdown: https://vonvon.id/sdks/backend/index.md
Source: https://vonvon.id/sdks/backend/index.mdx

## Runtime support

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

- Cloudflare Workers (primary target)
- Vercel Edge Runtime and Node.js server runtimes
- Any Web Crypto compatible runtime (Bun, Deno)

## authenticateRequest

Verify a Bearer or explicit application JWT from an incoming `Request`. A same-origin Core browser session is first exchanged through `/v1/sessions/token`; its opaque refresh cookie is never verified locally.

```ts
import { authenticateRequest } from '@vonvon-kit/backend'

const state = await authenticateRequest(request, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
})
if (state.isSignedIn) {
  console.log(state.userId)
}
```

## verifyToken

Low-level access token verification. Pass `jwtKey` from JWKS to skip network round-trips on cold start. Expected failures return a Result type, not an exception.

```ts
import { verifyToken } from '@vonvon-kit/backend'

const result = await verifyToken(token, {
  jwtKey: env.VONVON_JWKS_PUBLIC_KEY,
  issuer: 'https://vonvon.id',
  audience: 'my-api',
})
if (!result.ok) return new Response('Unauthorized', { status: 401 })
```

## verifyWebhook

Validates Svix-style webhook signatures (`svix-id`, `svix-timestamp`, `svix-signature`) with a five-minute replay window.

```ts
import { verifyWebhook } from '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_WEBHOOK_SECRET,
})
if (!result.ok) {
  return new Response('Invalid webhook', { status: 400 })
}
const { type, data } = result.value.payload
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `authenticateRequest` | function | Verify Bearer or explicit app JWT credentials, with optional same-origin Core session exchange |
| `exchangeSessionToken` | function | Forward Core opaque cookies only to an exact same-origin session-token endpoint; the value is never verified locally |
| `verifyToken` | function | Low-level access token verification: signature, exp, nbf, iss, aud, azp |
| `verifyWebhook` | function | Svix-style HMAC-SHA256 webhook signature validation with 5-minute replay window |
| `toVerifyKeySet` | function | Convert JwtKey (JWK, JWKS, or CryptoKey) to VerifyKeySet for verification |
| `JwksCache` | class | Optional network-fetching JWKS cache with configurable TTL (default 3600 s); use only when jwtKey is not pre-loaded |
| `AppError` | class | Thrown for unrecoverable SDK errors: missing JWT key, JWKS fetch failure, invalid options, session-token exchange failure |
| `BACKEND_ERROR_CODES` | as const tuple | All BackendErrorCode values: missing\_jwt\_key, jwks\_fetch\_failed, invalid\_options, session\_token\_exchange\_failed |
| `PACKAGE` | string constant | Package name identifier '@vonvon-kit/backend' |

## Types

| Type | Description |
| --- | --- |
| `JwtKey` | Accepted public key forms: PublicJwk, Jwks, or &#123; alg, publicKey: CryptoKey &#125; |
| `JwksCacheOptions` | Constructor options for JwksCache: jwksUri, ttlSec, fetchFn |
| `VerifyTokenOptions` | Options for verifyToken: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now |
| `VerifyTokenError` | Structured error returned when token verification fails (expected failure; not thrown) |
| `AuthenticateRequestOptions` | Options for authenticateRequest: jwtKey, issuer, audience, authorizedParties, clockToleranceSec, now, jwtCookieName, sessionTokenExchange |
| `RequestState` | Discriminated union of SignedInState and SignedOutState |
| `SignedInState` | Valid signed JWT state with userId, optional sessionId, and verified claims |
| `SignedOutState` | No valid token present; reason field indicates cause |
| `VerifyWebhookOptions` | Options for verifyWebhook: secret, toleranceSec (replay window seconds) |
| `WebhookVerifyError` | Structured error for missing headers, invalid signatures, replay, or invalid payloads |
| `VerifiedWebhook` | Verified message metadata and a typed type/data payload envelope |
| `BackendErrorCode` | Union of BACKEND\_ERROR\_CODES values |

## Security boundaries

- Uses public JWKS only. Never loads instance signing private keys.
- Verification uses Web Crypto via @vonvon-kit/crypto.
- Expected failures return Result types; unexpected errors throw AppError.

<!-- vonvon-doc-path: /sdks/react -->
<!-- vonvon-doc-slug: sdks/react -->
# @vonvon-kit/react

> React 19 provider, hooks, control components, and hosted UI building blocks for customer applications.

Locale: en
Canonical: https://vonvon.id/sdks/react
Markdown: https://vonvon.id/sdks/react/index.md
Source: https://vonvon.id/sdks/react/index.mdx

## Provider setup

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

```tsx
import { VonvonProvider } from '@vonvon-kit/react'

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
<VonvonProvider
  mode="oidc"
  issuer="https://vonvon.id"
  clientId="client_abc123"
  redirectUri="https://app.example.com/auth/callback"
>
  {children}
</VonvonProvider>
  )
}
```

## Hooks

| Hook | Returns |
| --- | --- |
| `useAuth` | isLoaded, isSignedIn, userId, signOut, getToken |
| `useUser` | isLoaded, isSignedIn, user: VonvonUser \| null |
| `useSession` | isLoaded, isSignedIn, session: VonvonSession \| null |
| `useSessionList` | isLoaded, sessions, setActive for multi-session switcher |
| `useSignIn` | Hosted Auth sign-in flow helpers |
| `useOrganization` | isLoaded, organization: VonvonOrganization \| null, membership |
| `useOrganizationList` | isLoaded, userMemberships for organization switcher UI |
| `useAPIKeys` | Management API key list and actions for console embeds |
| `useVonvonContext` | Raw VonvonContextValue (advanced use; prefer typed hooks above) |

## Control components

| Component | Props type | Purpose |
| --- | --- | --- |
| `SignedIn` | `SignedInProps` | Renders children only when the session is loaded and signed in |
| `SignedOut` | `SignedOutProps` | Renders children only when loaded and not signed in |
| `Protect` | `ProtectProps` | Permission and role gate with optional fallback UI |
| `VonvonLoaded` | `VonvonLoadedProps` | Renders children after SDK hydration completes (isLoaded true) |
| `VonvonLoading` | `VonvonLoadingProps` | Renders children while SDK is still loading (isLoaded false) |
| `VonvonFailed` | `VonvonFailedProps` | Renders children when SDK load fails with an unrecoverable error (status error) |
| `VonvonDegraded` | `VonvonDegradedProps` | Renders children when SDK is loaded but in degraded state (status degraded) |
| `AuthenticateWithRedirectCallback` | `AuthenticateWithRedirectCallbackProps` | OAuth redirect callback handler: reloads session state and redirects to afterSignInUrl or calls onSuccess |
| `RedirectToSignIn` | `RedirectToSignInProps` | Mounts and immediately redirects to the sign-in page |
| `RedirectToSignUp` | `RedirectToSignUpProps` | Mounts and immediately redirects to the sign-up page |
| `RedirectToUserProfile` | `RedirectToUserProfileProps` | Mounts and immediately redirects to the user profile page |
| `RedirectToOrganizationProfile` | `RedirectToOrganizationProfileProps` | Mounts and immediately redirects to the organization profile page |
| `RedirectToCreateOrganization` | `RedirectToCreateOrganizationProps` | Mounts and immediately redirects to the create organization page |
| `SignInButton` | `SignInButtonProps` | Unstyled button that navigates to the sign-in URL on click |
| `SignUpButton` | `SignUpButtonProps` | Unstyled button that navigates to the sign-up URL on click |
| `SignOutButton` | `SignOutButtonProps` | Unstyled button that calls signOut on click |

## UI components

| Component | Use |
| --- | --- |
| `SignIn` | Embedded sign-in panel (Hosted Auth) |
| `SignUp` | Embedded sign-up panel |
| `UserAvatar` | User avatar image with fallback initials |
| `UserButton` | Avatar menu with session switch and sign-out |
| `UserProfile` | Account security and profile management |
| `OrganizationSwitcher` | Active org selector |
| `OrganizationProfile` | Members, roles, SSO admin embed |
| `CreateOrganization` | Org creation flow |
| `OrganizationList` | List of user organizations for switcher UI |

## Not yet implemented

The following are on the public roadmap but are not exported from the current package. Do not assume availability in this version.

| Symbol | Design commitment |
| --- | --- |
| `GoogleOneTap` | One-tap sign-in embed |
| `Waitlist` | Waitlist sign-up gate component |
| Billing components | Usage and plan management embeds |
| `useReverification` | Step-up authentication hook |

## Appearance

Pass `appearance` to prebuilt UI components such as `SignIn`, `UserProfile`, or `OrganizationSwitcher`, not to `VonvonProvider`. The exported Appearance types provide typed CSS-variable and element-class overrides; all visible copy uses Lingui runtime descriptors.

<!-- vonvon-doc-path: /sdks/nextjs -->
<!-- vonvon-doc-slug: sdks/nextjs -->
# @vonvon-kit/nextjs

> Next.js middleware, App Router and Pages Router server helpers, plus React SDK re-exports.

Locale: en
Canonical: https://vonvon.id/sdks/nextjs
Markdown: https://vonvon.id/sdks/nextjs/index.md
Source: https://vonvon.id/sdks/nextjs/index.mdx

## Middleware

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

`vonvonMiddleware()` verifies a Bearer or explicit application JWT on the Edge Runtime. For a same-origin Core session, it exchanges the opaque cookie through `/v1/sessions/token`, verifies the returned JWT, and injects auth state into downstream server request headers.

```ts
import { vonvonMiddleware } from '@vonvon-kit/nextjs'

export default vonvonMiddleware({
  jwtKey: JSON.parse(process.env.VONVON_JWKS_PUBLIC_KEY!),
  issuer: 'https://vonvon.id',
  // This same-origin path must be routed to Vonvon Core.
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
})

export const config = {
  matcher: ['/dashboard(.*)', '/api/protected(.*)'],
}
```

## App Router server helpers

```ts
import { auth, currentUser } from '@vonvon-kit/nextjs'

export default async function DashboardPage() {
  const { userId } = await auth()
  if (!userId) return null
  const user = await currentUser()
  return <p>Welcome {user?.email}</p>
}
```

## Pages Router

```ts
import { getAuth } from '@vonvon-kit/nextjs'

export const getServerSideProps = async (ctx) => {
  const { userId } = await getAuth(ctx.req)
  if (!userId) return { redirect: { destination: '/sign-in', permanent: false } }
  return { props: {} }
}
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `vonvonMiddleware` | function | Edge Runtime middleware: verifies JWT, injects auth headers |
| `auth` | function | App Router: returns AuthObject with userId, orgId, orgRole |
| `getAuth` | function | Pages Router: returns AuthObject from IncomingMessage |
| `currentUser` | function | App Router: fetches full user object using server auth context |
| `vonvonClient` | function | Returns server-side VonvonApiClient bound to current request auth |
| `VONVON_AUTH_HEADER` | string constant | Header name for auth state between middleware and server components |
| `VonvonMiddlewareOptions` | type | Options for vonvonMiddleware: jwtKey, issuer, jwtCookieName, sessionTokenExchange, protectedRoutes, publicRoutes |
| `VonvonServerClientOptions` | type | Options for vonvonClient |
| `AuthObject` | type | Authenticated state: userId, orgId, orgRole, sessionId |
| `UnauthenticatedAuthObject` | type | Unauthenticated state with null fields |
| `AuthResult` | type | Union of AuthObject and UnauthenticatedAuthObject |
| `PaginationParams` | type | Cursor and limit params for Management API list calls |
| `PaginatedResponse<T>` | type | Paginated response envelope |

## Re-exports

- Re-exports all [@vonvon-kit/react](/sdks/react) client components and hooks via `export * from "@vonvon-kit/react"`.
- Re-exports from [@vonvon-kit/backend](/sdks/backend): `verifyToken`, `verifyWebhook`, `authenticateRequest`, `JwksCache`, `toVerifyKeySet`, `AppError`, `BACKEND_ERROR_CODES`, and all their associated types.
- Server helpers never expose signing secrets to client bundles.

<!-- vonvon-doc-path: /sdks/react-native -->
<!-- vonvon-doc-slug: sdks/react-native -->
# @vonvon-kit/react-native

> React Native provider and hooks for Hosted Auth redirect, PKCE S256, deep-link callback, and secure token storage adapters.

Locale: en
Canonical: https://vonvon.id/sdks/react-native
Markdown: https://vonvon.id/sdks/react-native/index.md
Source: https://vonvon.id/sdks/react-native/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. It implements a native token-session contract: Hosted Auth redirect with PKCE S256, state and nonce validation on the deep-link callback, verified ID token claims, authorization code exchange, and secure session persistence through an injected storage adapter.

A real IdP round-trip on production infrastructure is still pending manual verification. This page documents implemented behavior; it is not a readiness claim.

## Provider setup

Inject a `TokenCache` (platform secure storage) and a `BrowserInterface` (in-app browser) into `VonvonProvider`. The SDK does not hard-bind any native module; Expo apps can use the ready-made adapters from [@vonvon-kit/expo](/sdks/expo).

```tsx
import { VonvonProvider } from '@vonvon-kit/react-native'
import type { BrowserInterface, TokenCache } from '@vonvon-kit/react-native'
import * as Keychain from 'react-native-keychain'

const tokenCache: TokenCache = {
  async getToken(key) {
const result = await Keychain.getGenericPassword({ service: key })
return result ? result.password : null
  },
  async saveToken(key, value) {
await Keychain.setGenericPassword('vonvon', value, { service: key })
  },
  async deleteToken(key) {
await Keychain.resetGenericPassword({ service: key })
  },
}

const browser: BrowserInterface = {
  async openAuthSession(url, redirectUri) {
// Open url with your in-app browser library, wait for the redirectUri
// deep link, then return { type: 'success', url } or { type: 'cancel' }.
throw new Error('Implement with your preferred in-app browser library.')
  },
}

export function App() {
  return (
<VonvonProvider
  issuer="https://vonvon.id"
  clientId="your_client_id"
  redirectUri="myapp://auth/callback"
  tokenCache={tokenCache}
  browser={browser}
>
  <RootNavigator />
</VonvonProvider>
  )
}
```

## Sign in

`signIn()` builds the PKCE S256 authorize URL, stores the verifier, OAuth state, and nonce in the token cache, opens the browser adapter, and exchanges the returned code for a verified native session. Browser failure, state mismatch, ID token verification, and token exchange errors surface as `signInState.status === 'error'`.

```tsx
import { useSignIn } from '@vonvon-kit/react-native'

function SignInScreen() {
  const { signIn, signInState } = useSignIn()

  return (
<Button
  title={signInState.status === 'pending' ? 'Signing in...' : 'Sign in'}
  onPress={() => void signIn()}
/>
  )
}
```

## Deep link callback

When the browser adapter cannot capture the redirect itself, register the redirect URI scheme in your app manifest and forward the deep link to `handleRedirect(url)`. It validates and consumes the OAuth state, verifier, and nonce, exchanges the code, verifies the ID token, and stores the native session.

```tsx
import { useSignIn } from '@vonvon-kit/react-native'
import { useEffect } from 'react'
import { Linking } from 'react-native'

function DeepLinkHandler() {
  const { handleRedirect } = useSignIn()

  useEffect(() => {
const sub = Linking.addEventListener('url', ({ url }) => {
  if (url.startsWith('myapp://auth/callback')) {
    void handleRedirect(url)
  }
})
return () => sub.remove()
  }, [handleRedirect])

  return null
}
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `VonvonProvider` | component | Provides a native token-session context using tokenCache, browser, issuer, clientId, redirectUri, scopes, and optional fetcher |
| `useSignIn` | hook | signIn(options?) runs the full redirect flow; handleRedirect(url) processes a deep-link callback; signInState reports idle, pending, complete, cancelled, or error |
| `useSignOut` | hook | signOut() clears the local session and legacy credentials; signOutState reports progress or storage failures; no revoke request is sent |
| `useVonvonRnContext` | hook | Raw adapter context (advanced use and testing) |
| `exchangeCodeForTokens` | function | Low-level POST to the token endpoint with grant\_type authorization\_code and the PKCE verifier; returns a TokenSet |
| `saveTokenSet / clearTokenSet` | functions | Persist or remove the token set in the TokenCache adapter |
| `TOKEN_KEYS` | as const object | TokenCache key names for the current session envelope and pending PKCE, state, and nonce records; legacy token keys are cleanup-only |
| `createPkceVerifier / createPkceChallenge` | functions | PKCE S256 utilities delegated to @vonvon-kit/protocol (Web Crypto) |
| `createRandomString / base64UrlEncode` | functions | URL-safe random string for OAuth state; base64url encoding helper |

## Native hooks and controls

Unlike [@vonvon-kit/react](/sdks/react), this package uses its own native token context. It exports `useAuth`, `useUser`, `useSession`, `useSignIn`, `useSignOut`, `useVonvonRnContext`, `SignedIn`, `SignedOut`, `VonvonLoaded`, `VonvonLoading`, `exchangeCodeForTokens`, `saveTokenSet`, `readTokenSet`, and `clearTokenSet`; it does not import or re-export the React web SDK.

## Types

| Type | Description |
| --- | --- |
| `VonvonProviderProps` | Native provider props: children, tokenCache, browser, issuer, clientId, redirectUri, optional scopes (default openid, profile, email), and optional fetcher |
| `TokenCache` | Storage adapter contract: getToken, saveToken, deleteToken (all async) |
| `BrowserInterface` | openAuthSession(url, redirectUri) resolving to a BrowserResult |
| `BrowserResult` | Union of success (with callback URL), cancel, and dismiss |
| `SignInOptions` | Per-call overrides for signIn: redirectUri, scopes |
| `SignInState / SignOutState` | Discriminated status unions returned by the hooks |
| `UseSignInReturn / UseSignOutReturn` | Hook return shapes: actions plus state |
| `TokenExchangeInput / TokenSet` | Input and result of exchangeCodeForTokens: accessToken, idToken, expiresIn, and verified ID token claims |
| `VonvonRnContextValue` | Adapter context shape returned by useVonvonRnContext |

## Known limitations

- The SDK has no DPoP sender binding, rejects offline\_access, and requires a new authorization flow after the access token expires.
- useAuth().isSignedIn reflects a locally stored session only after ID token verification; it does not read a web cookie session.
- Organization context is not populated from stored tokens yet.

## Security

- Authorization code with PKCE S256 only. No implicit or password grant.
- Public clients never store client secrets.
- PKCE verifier and OAuth state live in the injected secure storage adapter and are deleted after the code exchange.
- signOut clears the local session and legacy credentials without a refresh or revoke request; storage failures surface in signOutState.

<!-- vonvon-doc-path: /sdks/vue -->
<!-- vonvon-doc-slug: sdks/vue -->
# @vonvon-kit/vue

> Vue 3 plugin, composables, and headless components on top of @vonvon-kit/core.

Locale: en
Canonical: https://vonvon.id/sdks/vue
Markdown: https://vonvon.id/sdks/vue/index.md
Source: https://vonvon.id/sdks/vue/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. Vue 3 plugin, composables, and headless components are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Plugin setup

Register `VonvonPlugin` once in `main.ts`. It creates an `VonvonClient` singleton, provides it via `VONVON_INJECTION_KEY`, and calls `client.load()` to hydrate session state.

```ts
// main.ts
import { createApp } from 'vue'
import { VonvonPlugin } from '@vonvon-kit/vue'
import App from './App.vue'

const app = createApp(App)
// This setup requires Core routes on the Vue application's exact origin.
app.use(VonvonPlugin, { mode: 'same-origin' })
app.mount('#app')
```

## Composables

```ts
import { useAuth, useUser, useOrganization, useSession } from '@vonvon-kit/vue'

const auth = useAuth()
// auth.isLoaded / auth.isSignedIn / auth.userId
// auth.getToken()  -> Promise<Result<string, VonvonError>>
// auth.signOut()   -> Promise<Result<null, VonvonError>>

const userRef = useUser()
// userRef.value.isLoaded && userRef.value.isSignedIn -> userRef.value.user.id

const orgRef = useOrganization()
// orgRef.value.organization / orgRef.value.membership / orgRef.value.setActive()

const sessionRef = useSession()
// sessionRef.value.session / sessionRef.value.getToken()
```

## Components

```vue
<template>
  <SignInButton sign-in-url="/sign-in" redirect-url="/dashboard">Log in</SignInButton>
  <SignOutButton redirect-url="/">Log out</SignOutButton>

  <Protect role="admin">
<AdminPanel />
<template #fallback><p>Access denied.</p></template>
  </Protect>

  <Protect permission="org:member:read">
<MemberList />
  </Protect>
</template>

<script setup lang="ts">
import { SignInButton, SignOutButton, Protect } from '@vonvon-kit/vue'
</script>
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `VonvonPlugin` | Vue plugin | app.use entry point; registers VonvonClient and calls client.load() |
| `createVonvonClient` | function | Factory that returns a standalone VonvonClient instance |
| `useVonvonClient` | composable | Returns the injected VonvonClient; throws if plugin is not registered |
| `VONVON_INJECTION_KEY` | InjectionKey | Symbol used to provide and inject the VonvonClient singleton |
| `useVonvon` | composable | Full state ref plus all client actions (UseVonvonReturn) |
| `useAuth` | composable | isLoaded, isSignedIn, userId, getToken, signOut |
| `useUser` | composable | Ref wrapping discriminated union on isLoaded / isSignedIn / user |
| `useOrganization` | composable | Active org, membership, and setActive action |
| `useSession` | composable | Active session and getToken action |
| `SignInButton` | component | Headless button that redirects to the sign-in URL on click |
| `SignOutButton` | component | Headless button that calls client.signOut() on click |
| `Protect` | component | Slot-based role and permission gate with default and fallback slots |

<!-- vonvon-doc-path: /sdks/nuxt -->
<!-- vonvon-doc-slug: sdks/nuxt -->
# @vonvon-kit/nuxt

> Nuxt 3 module with H3/Nitro server middleware and auto-imported Vue composables for SSR and full-stack apps.

Locale: en
Canonical: https://vonvon.id/sdks/nuxt
Markdown: https://vonvon.id/sdks/nuxt/index.md
Source: https://vonvon.id/sdks/nuxt/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. The Nuxt module, H3/Nitro server middleware, and auto-imported composables are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Module setup

Add `@vonvon-kit/nuxt` to the `modules` array. The module auto-imports all [@vonvon-kit/vue](/sdks/vue) composables and registers a client-only plugin that installs `VonvonPlugin`.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vonvon-kit/nuxt'],
  vonvon: {
browser: {
  mode: 'oidc',
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
},
  },
})
```

## Composables (auto-imported)

```vue
<script setup lang="ts">
// No import needed -- Nuxt auto-imports from @vonvon-kit/vue
const auth = useAuth()
const userRef = useUser()
const orgRef = useOrganization()
const sessionRef = useSession()
</script>

<template>
  <div v-if="auth.isSignedIn">
Signed in as {{ auth.userId }}
<button @click="auth.signOut()">Sign out</button>
  </div>
</template>
```

## Server middleware (JWT auth)

`createVonvonServerMiddleware` returns an H3 handler that verifies a Bearer or explicit application JWT and writes `event.context.vonvonAuth`. Configure same-origin Core sessions through `sessionTokenExchange`; H3 v1 relative URLs also require a trusted `requestOrigin`. Place the file in `server/middleware/` for global Nitro registration.

```ts
// server/middleware/vonvon.ts
import { createVonvonServerMiddleware } from '@vonvon-kit/nuxt'

export default createVonvonServerMiddleware({
  jwtKey: JSON.parse(process.env.VONVON_JWKS_PUBLIC_KEY!),
  issuer: 'https://acme.vonvon.id',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
  requestOrigin: process.env.VONVON_APP_ORIGIN!,
  protectedRoutes: ['/api/admin'],
})
```

## Reading auth in server routes

```ts
// server/routes/api/me.get.ts
import { getVonvonAuth } from '@vonvon-kit/nuxt'

export default defineEventHandler((event) => {
  const auth = getVonvonAuth(event)
  if (!auth.userId) {
throw createError({ statusCode: 401, message: 'Unauthorized' })
  }
  return { userId: auth.userId, orgId: auth.orgId }
})
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `createVonvonServerMiddleware` | function | H3 event handler factory: verifies JWT, writes event.context.vonvonAuth, protects routes |
| `getVonvonAuth` | function | Read AuthResult from event.context.vonvonAuth in server routes and handlers |
| `VONVON_AUTH_CONTEXT_KEY` | string constant | Context key used to store auth result ('vonvonAuth') |
| `VonvonServerMiddlewareOptions` | type | jwtKey, issuer, authorizedParties, jwtCookieName, sessionTokenExchange, requestOrigin, protectedRoutes, onUnauthenticated |

## Security notes

- `event.context.vonvonAuth` is server-side only and is never sent to the browser.
- The middleware strips any client-supplied auth tokens and re-injects only the verified result.
- Place the middleware file in `server/middleware/` to ensure it covers all routes as a global Nitro middleware.

<!-- vonvon-doc-path: /sdks/svelte -->
<!-- vonvon-doc-slug: sdks/svelte -->
# @vonvon-kit/svelte

> Svelte 5 reactive stores and SvelteKit server hook for client and SSR authentication.

Locale: en
Canonical: https://vonvon.id/sdks/svelte
Markdown: https://vonvon.id/sdks/svelte/index.md
Source: https://vonvon.id/sdks/svelte/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. Svelte 5 stores, SvelteKit server hook, and helper utilities are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Client setup

Create stores in the root layout using `createVonvonStores` and `setVonvonContext`. Stores use `VonvonClient.subscribe`, which satisfies the Svelte store subscriber contract.

```svelte
<!-- +layout.svelte -->
<script lang="ts">
  import { setContext, onMount } from 'svelte'
  import { VonvonClient, createVonvonStores, setVonvonContext } from '@vonvon-kit/svelte'

  // Core auth endpoints must be served on this application's exact origin.
  const client = new VonvonClient({ mode: 'same-origin' })
  const stores = createVonvonStores(client)
  setVonvonContext(setContext, stores)

  onMount(() => {
const ac = new AbortController()
void client.load({ signal: ac.signal })
return () => ac.abort()
  })
</script>
<slot />
```

## Reading auth state

```svelte
<!-- Any child component -->
<script lang="ts">
  import { getContext } from 'svelte'
  import { getVonvonContext } from '@vonvon-kit/svelte'

  const { auth, user } = getVonvonContext(getContext)
  // $auth: { isLoaded, isSignedIn, userId, sessionId, session }
  // $user: discriminated union on isLoaded / isSignedIn / user
</script>

{#if !$auth.isLoaded}
  <p>Loading...</p>
{:else if $auth.isSignedIn}
  <p>Hello, {$user.isSignedIn ? $user.user.fullName : ''}</p>
{:else}
  <p>Not signed in</p>
{/if}
```

## Sign-in and sign-out

```svelte
<script lang="ts">
  import { getContext } from 'svelte'
  import { getVonvonContext, buildSignInUrl, executeSignOut } from '@vonvon-kit/svelte'

  const { client } = getVonvonContext(getContext)

  function handleSignIn() {
window.location.assign(buildSignInUrl('/sign-in', window.location.href))
  }

  async function handleSignOut() {
await executeSignOut(client, { redirectUrl: '/' })
  }
</script>
```

## Role and permission guard

```svelte
<script lang="ts">
  import { getContext } from 'svelte'
  import { getVonvonContext, isAllowed } from '@vonvon-kit/svelte'

  const { state } = getVonvonContext(getContext)
</script>

{#if isAllowed($state, { role: 'admin' })}
  <AdminPanel />
{/if}

{#if isAllowed($state, { permission: 'org:member:write' })}
  <EditButton />
{/if}
```

## SvelteKit server hook

```ts
// src/hooks.server.ts
import { handleVonvon } from '@vonvon-kit/svelte/server'

export const handle = handleVonvon({
  jwtKey: JSON.parse(process.env.VONVON_JWKS_PUBLIC_KEY!),
  issuer: 'https://vonvon.id',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
  protectedRoutes: ['/dashboard', '/account'],
  signInUrl: '/sign-in',
})
```

## Reading auth in load functions

```ts
// +page.server.ts
import { redirect } from '@sveltejs/kit'
import { getVonvonAuth } from '@vonvon-kit/svelte/server'
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ locals }) => {
  const auth = getVonvonAuth(locals)
  if (!auth.userId) throw redirect(303, '/sign-in')
  return { userId: auth.userId, orgId: auth.orgId }
}
```

## App.Locals typing

```ts
// src/app.d.ts
import type { AuthResult } from '@vonvon-kit/svelte/server'

declare global {
  namespace App {
interface Locals {
  vonvonAuth: AuthResult
}
  }
}
export {}
```

## Exported API

| Export | Kind | Module |
| --- | --- | --- |
| `VonvonClient, createVonvonStores, setVonvonContext, getVonvonContext` | client setup | `@vonvon-kit/svelte` |
| `buildSignInUrl, executeSignOut, isAllowed` | utilities | `@vonvon-kit/svelte` |
| `handleVonvon, getVonvonAuth` | server hook | `@vonvon-kit/svelte/server` |

<!-- vonvon-doc-path: /sdks/solid -->
<!-- vonvon-doc-slug: sdks/solid -->
# @vonvon-kit/solid

> SolidJS context provider, signal-based auth primitives, and headless components on top of @vonvon-kit/core.

Locale: en
Canonical: https://vonvon.id/sdks/solid
Markdown: https://vonvon.id/sdks/solid/index.md
Source: https://vonvon.id/sdks/solid/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. SolidJS context provider, signal-based primitives, and headless components are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Provider setup

Wrap your app with `VonvonProvider`. It creates an `VonvonClient`, calls `client.load()` on mount to fetch the current session, and tears down via `onCleanup`.

```tsx
import { VonvonProvider } from '@vonvon-kit/solid'

export function App() {
  return (
<VonvonProvider
  mode="oidc"
  issuer="https://vonvon.id"
  clientId="client_abc123"
  redirectUri="https://app.example.com/auth/callback"
>
  <Routes />
</VonvonProvider>
  )
}
```

## Auth primitives

Each primitive returns reactive `Accessor<T>` (getter functions). Call them in JSX or `createEffect` to track changes.

```tsx
import { createAuth, createUser, createOrganization, createSession } from '@vonvon-kit/solid'
import { Show } from 'solid-js'

function Profile() {
  const auth = createAuth()
  // auth.isLoaded()  -- Accessor<boolean>
  // auth.isSignedIn() -- Accessor<boolean>
  // auth.userId()    -- Accessor<string | null>
  // auth.getToken()  -- () => Promise<Result<string, VonvonError>>
  // auth.signOut()   -- (options?) => Promise<Result<null, VonvonError>>

  return (
<Show when={auth.isLoaded()} fallback={<p>Loading...</p>}>
  <Show when={auth.isSignedIn()} fallback={<p>Not signed in</p>}>
    <p>Signed in as {auth.userId()}</p>
    <button onClick={() => void auth.signOut()}>Sign out</button>
  </Show>
</Show>
  )
}
```

## createOrganization and createSession

```tsx
const org = createOrganization()
// org() is CreateOrganizationReturn
if (org().isSignedIn) {
  console.log(org().organization?.name, org().membership?.role)
  const activated = await org().setActive('org_new_id')
  if (!activated.ok) throw new Error(activated.error.message)
}

const session = createSession()
if (session().isSignedIn) {
  const token = await session().getToken()
  if (!token.ok) throw new Error(token.error.message)
  // use token.value for backend requests
}
```

## Headless components

```tsx
import { SignInButton, SignOutButton, Protect } from '@vonvon-kit/solid'

// Navigates to /sign-in by default
<SignInButton signInUrl="/auth/sign-in" redirectUrl="/dashboard">
  Log in
</SignInButton>

// Signs out all sessions; pass sessionId to target one
<SignOutButton redirectUrl="/home">Log out</SignOutButton>

// Role and permission gate
<Protect role="admin" fallback={<p>Admins only</p>}>
  <Settings />
</Protect>

<Protect permission="org:member:write" fallback={null}>
  <InviteForm />
</Protect>
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `VonvonProvider` | component | Creates VonvonClient, calls load() on mount, tears down via onCleanup |
| `createAuth` | primitive | isLoaded, isSignedIn, userId, sessionId, session, getToken, signOut as Accessors |
| `createUser` | primitive | Accessor wrapping discriminated union on isLoaded / isSignedIn / user |
| `createOrganization` | primitive | Accessor returning organization, membership, and setActive for the active org |
| `createSession` | primitive | Accessor returning session and getToken for the active session |
| `SignInButton` | component | Headless button navigating to the sign-in URL on click |
| `SignOutButton` | component | Headless button that calls signOut on click |
| `Protect` | component | Role and permission gate with fallback prop |

## Token storage

- The Vonvon Worker keeps an opaque refresh credential in an `HttpOnly` cookie. It is not a JWT, and the SDK never reads it from JavaScript or stores it in `localStorage`.
- `getToken()` returns a short-lived JWT (60 s) cached only in memory by `TokenManager` in `@vonvon-kit/core`.

<!-- vonvon-doc-path: /sdks/angular -->
<!-- vonvon-doc-slug: sdks/angular -->
# @vonvon-kit/angular

> Angular 17+ standalone provider, RxJS service, functional route guards, and standalone components on top of @vonvon-kit/core.

Locale: en
Canonical: https://vonvon.id/sdks/angular
Markdown: https://vonvon.id/sdks/angular/index.md
Source: https://vonvon.id/sdks/angular/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. Angular 17+ standalone provider, RxJS service, functional guards, and standalone components are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Provider setup

Call `provideVonvon` in `app.config.ts`. It registers the `VONVON_CLIENT` injection token and wires an `APP_INITIALIZER` that calls `client.load()` on bootstrap. No NgModule required.

```ts
// app.config.ts
import { ApplicationConfig } from '@angular/core'
import { provideVonvon } from '@vonvon-kit/angular'

export const appConfig: ApplicationConfig = {
  providers: [
// Core auth endpoints must be served on this application's exact origin.
provideVonvon({ mode: 'same-origin' }),
  ],
}
```

## VonvonAuthService

```ts
import { Component, inject } from '@angular/core'
import { AsyncPipe } from '@angular/common'
import { VonvonAuthService } from '@vonvon-kit/angular'

@Component({
  selector: 'app-header',
  standalone: true,
  imports: [AsyncPipe],
  template: `
@if (auth.isLoaded$ | async) {
  @if (auth.isSignedIn$ | async) {
    <span>{{ (auth.user$ | async)?.primaryEmailAddress }}</span>
  } @else {
    <a routerLink="/sign-in">Sign in</a>
  }
}
  `,
})
export class HeaderComponent {
  readonly auth = inject(VonvonAuthService)
}
```

## Angular signals bridge

Use `toSignal()` from `@angular/core/rxjs-interop` to convert observables to signals for template reads.

```ts
import { toSignal } from '@angular/core/rxjs-interop'
import { inject } from '@angular/core'
import { VonvonAuthService } from '@vonvon-kit/angular'

@Component({ standalone: true, ... })
export class MyComponent {
  readonly #auth = inject(VonvonAuthService)
  readonly user = toSignal(this.#auth.user$, { initialValue: null })
}
```

## Route guards

```ts
import { Routes } from '@angular/router'
import { authGuard, hasOrganizationGuard, hasPermissionGuard } from '@vonvon-kit/angular'

export const routes: Routes = [
  {
path: 'dashboard',
canActivate: [authGuard()],
loadComponent: () => import('./dashboard.component').then(m => m.DashboardComponent),
  },
  {
path: 'admin',
canActivate: [hasPermissionGuard('org:settings:write')],
loadComponent: () => import('./admin.component').then(m => m.AdminComponent),
  },
]
```

## Standalone components

```html
<!-- template -->
<vonvon-sign-in-button signInUrl="/sign-in" redirectUrl="/dashboard">Log in</vonvon-sign-in-button>
<vonvon-sign-out-button redirectUrl="/home">Log out</vonvon-sign-out-button>
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `provideVonvon` | function | Registers VONVON\_CLIENT singleton and APP\_INITIALIZER; accepts ProvideVonvonOptions |
| `VONVON_CLIENT` | InjectionToken | The raw VonvonClient instance; prefer VonvonAuthService for most use cases |
| `VonvonAuthService` | service | RxJS observables: state$, isLoaded$, isSignedIn$, user$, session$, organization$; plus getToken, signOut, setActiveOrganization, setActiveSession |
| `authGuard` | CanActivateFn factory | Redirects to /sign-in when user is not signed in |
| `hasOrganizationGuard` | CanActivateFn factory | Redirects when no active organization context is present |
| `hasPermissionGuard` | CanActivateFn factory | Redirects when user lacks the specified permission |
| `SignInButton` | standalone component | Selector vonvon-sign-in-button; inputs signInUrl, redirectUrl, ariaLabel |
| `SignOutButton` | standalone component | Selector vonvon-sign-out-button; inputs sessionId, redirectUrl, ariaLabel; shows aria-busy while signing out |

<!-- vonvon-doc-path: /sdks/astro -->
<!-- vonvon-doc-slug: sdks/astro -->
# @vonvon-kit/astro

> Astro integration with SSR middleware, server helpers, and island client singleton for static and server-rendered Astro sites.

Locale: en
Canonical: https://vonvon.id/sdks/astro
Markdown: https://vonvon.id/sdks/astro/index.md
Source: https://vonvon.id/sdks/astro/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. The Astro integration, SSR middleware, server helpers, and island client singleton are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Integration setup

Register `vonvonIntegration` in `astro.config.mjs`. The integration injects server middleware with `addMiddleware` at order `pre`, keeps verification material server-side, and exposes only the serializable browser mode configuration required by client islands.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'
import { vonvonIntegration } from '@vonvon-kit/astro'
import node from '@astrojs/node'

const jwtKeyJson = process.env.VONVON_JWKS_PUBLIC_KEY
if (!jwtKeyJson) throw new Error('Missing VONVON_JWKS_PUBLIC_KEY')

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
vonvonIntegration({
  // This combined SSR setup requires Core routes on the application's exact origin.
  browser: { mode: 'same-origin' },
  jwtKey: JSON.parse(jwtKeyJson),
  issuer: 'https://app.example.com',
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
  protectedRoutes: ['/dashboard', '/account'],
  signInUrl: '/sign-in',
}),
  ],
})
```

## Manual middleware (alternative)

```ts
// src/middleware.ts
import { sequence } from 'astro:middleware'
import { createVonvonMiddleware } from '@vonvon-kit/astro'

export const onRequest = sequence(
  createVonvonMiddleware({
jwtKey: JSON.parse(import.meta.env.VONVON_JWKS_PUBLIC_KEY),
issuer: 'https://vonvon.id',
sessionTokenExchange: { endpoint: '/v1/sessions/token' },
protectedRoutes: ['/dashboard', '/account'],
signInUrl: '/sign-in',
  }),
)
```

## Server-side auth in .astro pages

```astro
---
// src/pages/dashboard.astro
import { getAuth, currentUser } from '@vonvon-kit/astro/server'

const auth = getAuth(Astro.locals)
if (!auth.userId) return Astro.redirect('/sign-in')

const user = await currentUser(Astro.locals, {
  secretKey: import.meta.env.VONVON_SECRET_KEY,
})
---

<h1>Welcome, {user?.primaryEmailAddress}</h1>
```

## Client island

```tsx
// src/components/SignOutButton.tsx
import { getClient } from '@vonvon-kit/astro/client'

export default function SignOutButton() {
  const client = getClient()

  const handleSignOut = async () => {
const result = await client.signOut()
if (!result.ok) throw new Error(result.error.message)
window.location.href = '/'
  }

  return <button onClick={handleSignOut}>Sign out</button>
}
```

## Astro.locals typing

Add the type reference to `src/env.d.ts` to get full type coverage on `Astro.locals.vonvonAuth`.

```ts
import '@vonvon-kit/astro/locals'
```

## Exported API

| Export | Kind | Module |
| --- | --- | --- |
| `vonvonIntegration` | Astro integration factory | `@vonvon-kit/astro` |
| `createVonvonMiddleware` | middleware factory | `@vonvon-kit/astro` |
| `getAuth, currentUser, vonvonClient` | server helpers | `@vonvon-kit/astro/server` |
| `getClient, initClient, resetClient` | island client singleton | `@vonvon-kit/astro/client` |

## Security notes

- `jwtKey` is a JWKS public key; it is safe for networkless verification and does not contain a private key.
- `secretKey` (`sk_live_xxx`) must stay server-side only; never pass it to an island or client bundle.
- Protected routes redirect via `Response.redirect` in middleware before any page handler runs; no client-side JS is required.
- Forward Core opaque cookies only to an exact same-origin session-token endpoint; the value is never verified locally

<!-- vonvon-doc-path: /sdks/remix -->
<!-- vonvon-doc-slug: sdks/remix -->
# @vonvon-kit/remix

> Remix loader and action server helpers, cookie session storage, and OAuth callback handler with React SDK re-exports.

Locale: en
Canonical: https://vonvon.id/sdks/remix
Markdown: https://vonvon.id/sdks/remix/index.md
Source: https://vonvon.id/sdks/remix/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. Remix loader/action auth helpers, cookie session integration, and OAuth callback handler are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Session storage setup

```ts
// app/sessions.server.ts
import { createVonvonSessionStorage } from '@vonvon-kit/remix'

export const sessionStorage = createVonvonSessionStorage({
  secret: process.env.SESSION_SECRET!, // required: cookie signing secret
  // cookieName: '__vonvon_session', maxAge: 2592000, secure: true
})
```

## Reading auth in loaders

`getAuth` verifies a Bearer token, explicit application JWT cookie, optional same-origin Core exchange, or the configured Remix session JWT, then returns an `AuthResult`. `requireAuth` throws a 302 redirect to `redirectPath` when unauthenticated.

```ts
import { getAuth, requireAuth } from '@vonvon-kit/remix'
import { json, redirect } from '@remix-run/node'
import type { LoaderFunctionArgs } from '@remix-run/node'
import { sessionStorage } from '~/sessions.server'

const jwtKey = JSON.parse(process.env.VONVON_JWKS_PUBLIC_KEY!)
const authOptions = {
  jwtKey,
  sessionStorage,
  sessionTokenExchange: { endpoint: '/v1/sessions/token' },
}

// Optional check
export async function loader({ request }: LoaderFunctionArgs) {
  const auth = await getAuth(request, authOptions)
  if (!auth.userId) return redirect('/login')
  return json({ userId: auth.userId, orgId: auth.orgId })
}

// Guard: throws redirect automatically when unauthenticated
export async function protectedLoader({ request }: LoaderFunctionArgs) {
  const auth = await requireAuth(request, authOptions, { redirectPath: '/login' })
  return json({ userId: auth.userId })
}
```

## OAuth callback handler

`handleCallback` validates the `state` parameter to prevent CSRF, exchanges the authorization code, and returns a `Response` with `Set-Cookie`.

```ts
// app/routes/auth.callback.ts
import { handleCallback } from '@vonvon-kit/remix'
import type { ActionFunctionArgs } from '@remix-run/node'
import { sessionStorage } from '~/sessions.server'

export async function action({ request }: ActionFunctionArgs) {
  const result = await handleCallback(request, {
clientId: process.env.VONVON_CLIENT_ID!,
redirectUri: process.env.VONVON_REDIRECT_URI!,
sessionStorage,
defaultReturnTo: '/dashboard',
  })

  if (!result.ok) throw new Response(result.error, { status: 400 })
  return result.response // 302 redirect + Set-Cookie
}
```

## Client provider (root.tsx)

```tsx
import { VonvonProvider } from '@vonvon-kit/remix' // re-export from @vonvon-kit/react
import { Outlet } from '@remix-run/react'

export default function App() {
  return (
<VonvonProvider
  mode="oidc"
  issuer="https://vonvon.id"
  clientId="client_abc123"
  redirectUri="https://app.example.com/auth/callback"
>
  <Outlet />
</VonvonProvider>
  )
}
```

## Management API client

```ts
import { vonvonClient } from '@vonvon-kit/remix'

const client = vonvonClient({ secretKey: process.env.VONVON_SECRET_KEY! })

export async function loader() {
  const result = await client.getUser('user_abc')
  if (!result.ok) throw new Response(result.error.message, { status: result.error.status })
  return json(result.value)
}
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `createVonvonSessionStorage` | function | Remix cookie session storage for Vonvon tokens |
| `getAuth` | function | Verify JWT or session token; returns AuthResult |
| `requireAuth` | function | Like getAuth but throws a redirect response when unauthenticated |
| `handleCallback` | function | OAuth callback: validates state, exchanges code, sets session cookie |
| `vonvonClient` | function | Returns a server-side Management API client bound to the secret key |
| `getTokenFromSession, setTokensInSession, clearTokensFromSession` | functions | Low-level token helpers for custom session handling |

## Re-exports

Re-exports all [@vonvon-kit/react](/sdks/react) client components and hooks. `root.tsx` needs only one import for both provider and client components.

## PKCE and security

- Public clients use Authorization Code with PKCE S256. No client secret is stored.
- `handleCallback` validates the `state` parameter against the session to prevent CSRF.
- Access tokens are stored in `HttpOnly` session cookies; they are never written to `localStorage`.

<!-- vonvon-doc-path: /sdks/expo -->
<!-- vonvon-doc-slug: sdks/expo -->
# @vonvon-kit/expo

> Expo SecureStore and WebBrowser adapters for @vonvon-kit/react-native plus an Expo Router route guard hook.

Locale: en
Canonical: https://vonvon.id/sdks/expo
Markdown: https://vonvon.id/sdks/expo/index.md
Source: https://vonvon.id/sdks/expo/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. Expo SecureStore and WebBrowser adapters, VonvonProvider, and Expo Router route guard hook are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

All PKCE logic, token exchange, and session management live in [@vonvon-kit/react-native](/sdks/react-native); this package provides adapters and Expo Router integration only.

## Provider setup

Inject `createSecureStoreAdapter` and `createExpoWebBrowserAdapter` into `VonvonProvider`. No top-level Expo module import is needed; adapters accept module instances so CI typecheck stays clean without Expo peer deps installed.

```tsx
import * as SecureStore from 'expo-secure-store'
import * as WebBrowser from 'expo-web-browser'
import { VonvonProvider, createSecureStoreAdapter, createExpoWebBrowserAdapter } from '@vonvon-kit/expo'

const tokenCache = createSecureStoreAdapter({ secureStore: SecureStore })
const browser = createExpoWebBrowserAdapter({ webBrowser: WebBrowser })

export default function App() {
  return (
<VonvonProvider
  issuer="https://vonvon.id"
  clientId="your_client_id"
  redirectUri="myapp://auth/callback"
  tokenCache={tokenCache}
  browser={browser}
>
  <RootLayout />
</VonvonProvider>
  )
}
```

## Sign in and sign out

```tsx
import { useSignIn, useSignOut } from '@vonvon-kit/expo'
import { Button } from 'react-native'

function SignInScreen() {
  const { signIn, signInState } = useSignIn()
  return (
<Button
  title={signInState.status === 'pending' ? 'Signing in...' : 'Sign In'}
  onPress={() => void signIn()}
/>
  )
}

function SignOutScreen() {
  const { signOut } = useSignOut()
  return <Button title="Sign Out" onPress={() => void signOut()} />
}
```

## Expo Router route guard

Call `useProtectedRoute` in a layout component. It reads `isLoaded`/`isSignedIn` from `useAuth` and calls `replace` from Expo Router inside a `useEffect`.

```tsx
import { useProtectedRoute } from '@vonvon-kit/expo'
import { useRouter, usePathname } from 'expo-router'

export default function RootLayout() {
  const router = useRouter()
  const pathname = usePathname()

  useProtectedRoute({
signInRoute: '/sign-in',
protectedRoute: '/(app)',
pathname,
replace: router.replace,
  })

  return <Slot />
}
```

## SecureStore key namespacing

Use `keyPrefix` to namespace keys under a custom prefix. The separator is `.` (dot), which is within the allowed character set for `expo-secure-store`.

```ts
const tokenCache = createSecureStoreAdapter({
  secureStore: SecureStore,
  keyPrefix: 'myapp',
  // Current session key: 'myapp.vonvon.session.v1'.
})
```

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `VonvonProvider` | component | Re-export of @vonvon-kit/react-native VonvonProvider accepting tokenCache and browser adapters |
| `createSecureStoreAdapter` | function | TokenCache adapter backed by expo-secure-store; accepts secureStore instance and optional keyPrefix |
| `createExpoWebBrowserAdapter` | function | BrowserInterface adapter backed by expo-web-browser |
| `useSignIn` | hook | Re-export from @vonvon-kit/react-native: signIn, handleRedirect, signInState |
| `useSignOut` | hook | Re-export from @vonvon-kit/react-native: signOut, signOutState |
| `useProtectedRoute` | hook | Reads isLoaded/isSignedIn and calls Expo Router replace for route protection |

## Known limitations

- `useAuth().isSignedIn` reflects the locally stored, verified native session from `VonvonProvider`. It does not read a web cookie session; offline\_access is rejected until DPoP sender binding is implemented, and access-token expiry requires reauthorization.
- This package provides only adapters and Expo Router integration. For the base React Native PKCE flow, see [@vonvon-kit/react-native](/sdks/react-native).

<!-- vonvon-doc-path: /sdks/electron -->
<!-- vonvon-doc-slug: sdks/electron -->
# @vonvon-kit/electron

> Electron SDK with main process PKCE flow, contextBridge preload, OS keychain token storage, and loopback or custom-scheme callback strategies.

Locale: en
Canonical: https://vonvon.id/sdks/electron
Markdown: https://vonvon.id/sdks/electron/index.md
Source: https://vonvon.id/sdks/electron/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. Main process app, contextBridge preload, and renderer-side bridge are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Entry points

| Entry | Purpose |
| --- | --- |
| `@vonvon-kit/electron` | Default export: renderer surface and types |
| `@vonvon-kit/electron/main` | Main process only: VonvonElectronApp |
| `@vonvon-kit/electron/renderer` | Renderer process: getVonvonBridge, VonvonClient |
| `@vonvon-kit/electron/preload` | Ready-made preload script that exposes window.vonvonBridge |

## Main process setup

```ts
// main.ts
import { app, ipcMain } from 'electron'
import { VonvonElectronApp } from '@vonvon-kit/electron/main'

const vonvonApp = new VonvonElectronApp({
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  // callbackStrategy: 'loopback' (default, RFC 8252 s.7.3) | 'custom-scheme'
})

app.whenReady().then(async () => {
  await vonvonApp.init(ipcMain)
  const win = new BrowserWindow({
webPreferences: {
  contextIsolation: true,
  preload: path.join(__dirname, 'preload.js'),
},
  })
  win.on('closed', () => vonvonApp.dispose(ipcMain))
})
```

## Preload script

```ts
// preload.ts
import '@vonvon-kit/electron/preload'
// Exposes window.vonvonBridge with storage, signIn, signOut,
// getAccessToken, getSession, setTokenStorage
```

## Renderer process

```ts
import { getVonvonBridge } from '@vonvon-kit/electron/renderer'

const bridge = getVonvonBridge()

// Opens system browser, waits for loopback callback, exchanges code.
const accessToken = await bridge.signIn()

// Get the current unexpired access token. Expiry requires a new sign-in.
const token = await bridge.getAccessToken() // null when signed out or expired

// Get the current unexpired session (accessToken + expiresAt in epoch seconds).
const session = await bridge.getSession()

// Clear local tokens. No refresh or revoke request is sent.
await bridge.signOut()
```

## Custom scheme (alternative to loopback)

```ts
// main.ts
import { app } from 'electron'
import { VonvonElectronApp } from '@vonvon-kit/electron/main'

app.setAsDefaultProtocolClient('myapp')

const vonvonApp = new VonvonElectronApp({
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  callbackStrategy: 'custom-scheme',
  customScheme: 'myapp',  // redirect_uri = myapp://callback
})

vonvonApp.registerDeepLinkHandler(app)
```

## Token storage

- Tokens are encrypted with `safeStorage.encryptString()` (OS keychain) and stored as binary files in `app.getPath('userData')/vonvon-tokens/` by default.
- If `safeStorage.isEncryptionAvailable()` returns `false` (headless Linux without a keyring), `setItem()` throws `ElectronStorageError` with code `encryption_unavailable` rather than writing plaintext silently.
- Override the storage directory with `storageDir` in `VonvonElectronMainOptions`.

## Shared native contract

| Method | Description |
| --- | --- |
| `signIn(options?)` | Opens system browser, exchanges code, stores tokens |
| `signOut()` | Clears local tokens |
| `getAccessToken()` | Returns the current unexpired access token without refresh; clears expired local state and returns null. The SDK rejects offline\_access until DPoP is implemented. |
| `getSession()` | Returns the current unexpired accessToken and expiresAt, or null |

<!-- vonvon-doc-path: /sdks/tauri -->
<!-- vonvon-doc-slug: sdks/tauri -->
# @vonvon-kit/tauri

> Tauri v2 desktop SDK with PKCE S256 flow, deeplink callback handler, OS keychain adapter, and Rust plugin template.

Locale: en
Canonical: https://vonvon.id/sdks/tauri
Markdown: https://vonvon.id/sdks/tauri/index.md
Source: https://vonvon.id/sdks/tauri/index.mdx

## Status

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Package status is **Current package**. JS bridge, PKCE S256 flow, deeplink callback handler, OS keychain adapter, and Rust plugin template are implemented. A real IdP round-trip on production infrastructure is still pending manual verification.

## Tauri configuration

```json
// tauri.conf.json
{
  "bundle": { "identifier": "com.example.myapp" },
  "plugins": {
"deep-link": { "desktop": { "schemes": ["myapp"] } }
  }
}
```

## Rust plugin

Copy `templates/vonvon-keychain-plugin.rs` into `src-tauri/src/vonvon_keychain.rs` and register it following `templates/tauri-app-setup.rs`. Add `keyring = "2"`, `tauri-plugin-deep-link = "2"`, and `tauri-plugin-shell = "2"` to `src-tauri/Cargo.toml`.

## JS integration

```ts
import { createVonvonTauriClient, createTauriKeychainAdapter } from '@vonvon-kit/tauri'
import { invoke } from '@tauri-apps/api/core'
import { open } from '@tauri-apps/plugin-shell'
import { onOpenUrl } from '@tauri-apps/plugin-deep-link'

const client = createVonvonTauriClient({
  issuer: 'https://vonvon.id',
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'myapp://auth/callback',
  keychain: createTauriKeychainAdapter({ invoke }),
})

// Register deeplink handler (e.g. on App component mount)
await onOpenUrl(async (urls) => {
  for (const url of urls) await client.handleRedirect(url)
})

// Trigger sign-in: opens system browser
await client.signIn({ openUrl: open })
```

## Token retrieval and sign-out

```ts
// Get the current unexpired access token. Expiry requires a new sign-in.
const token = await client.getAccessToken()

// Get the current unexpired session (userId, organizationId, expiresAt).
const session = await client.getSession()

// Clear local keychain state. No refresh or revoke request is sent.
await client.signOut()

// To request full IdP sign-out, open an explicit OIDC RP-initiated logout URL.
const logoutUrl = client.buildSignOutUrl({ postLogoutRedirectUri: 'myapp://logout' })
await open(logoutUrl.toString())
```

## Dev/test without Tauri runtime

```ts
import { createVonvonTauriClient, createMemoryKeychainAdapter } from '@vonvon-kit/tauri'

const client = createVonvonTauriClient({
  issuer: 'http://localhost:8788',
  clientId: 'test-client',
  redirectUri: 'http://localhost:1420/callback',
  keychain: createMemoryKeychainAdapter(),
})
```

## createVonvonTauriClient options

| Option | Type | Description |
| --- | --- | --- |
| `issuer` | string | Vonvon issuer URL |
| `clientId` | string | OAuth 2.0 client\_id |
| `redirectUri` | string | Custom URI scheme callback |
| `scopes` | readonly string\[\] | Default: openid, profile, email |
| `keychain` | VonvonKeychainAdapter | Token storage adapter; default is MemoryKeychainAdapter (use Tauri adapter in production) |

## VonvonTauriClient methods

| Method | Description |
| --- | --- |
| `signIn(options?)` | Build PKCE authorize URL; open via openUrl callback |
| `handleRedirect(url)` | Parse deeplink, validate state, exchange code for tokens |
| `getSession()` | TauriSession or null for a current unexpired local session; expired state is cleared |
| `getAccessToken(options?)` | Current unexpired access token string or null; no refresh request is performed. The SDK rejects offline\_access until DPoP is implemented. |
| `signOut()` | Clear local keychain state without a revoke request |
| `buildSignOutUrl(options?)` | Build OIDC end\_session URL for RP-initiated logout |
| `setTokenStorage(adapter)` | Swap keychain adapter at runtime |

## PKCE and token storage

- PKCE S256 is always used. Plain challenge is never generated.
- Verifier entropy is 64 bytes; challenge derived via Web Crypto `crypto.subtle.digest('SHA-256', ...)`.
- All keys are namespaced under `vonvon.*`. `vonvon.access_token` is current. `vonvon.refresh_token` is removed only as legacy cleanup. `vonvon.session`, `vonvon.pkce_verifier`, and `vonvon.oauth_state` hold current session and authorization state; no refresh credential is read or written.

<!-- vonvon-doc-path: /sdks/go -->
<!-- vonvon-doc-slug: sdks/go -->
# sdk/go

> Go server SDK for networkless JWT verification, request authentication, and webhook signature validation.

Locale: en
Canonical: https://vonvon.id/sdks/go
Markdown: https://vonvon.id/sdks/go/index.md
Source: https://vonvon.id/sdks/go/index.mdx

## Status

Implemented and verified locally. Real IdP round-trip verification (JWKS fetch, token sign/verify against a live Vonvon instance) has not been performed yet and must be completed before production use.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Request authentication is Bearer-only by default. An application-owned JWT cookie is read only when its exact name is configured. The opaque \_\_Host-vonvon.rt.\* Core cookie is never scanned or verified locally; exchange it by forwarding the complete Cookie header to exact same-origin POST /v1/sessions/token with redirects disabled, and accept only a response containing the token field.

## Install

```shell
go get github.com/StringKe/vonvon/sdk/go@main
```

## Quick start

Create one `Client` at application startup and reuse it across requests. The client caches JWKS internally with a configurable TTL.

```go
import "github.com/StringKe/vonvon/sdk/go/vonvon"

client, err := vonvon.NewClient(vonvon.ClientOptions{
Issuer:        "https://vonvon.id",
Audience:      "your-client-id",
WebhookSecret: "whs_...",
})
if err != nil {
log.Fatal(err)
}

// HTTP middleware (recommended)
http.Handle("/api/", client.Middleware(apiHandler, func(w http.ResponseWriter, r *http.Request) {
http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
}))

// Inside a protected handler
func apiHandler(w http.ResponseWriter, r *http.Request) {
claims := vonvon.ClaimsFromContext(r.Context())
fmt.Fprintf(w, "hello %s", claims.Subject)
}
```

## Verify token directly

```go
claims, err := client.VerifyAccessToken(ctx, tokenString)
if err != nil {
// handle verification failure
}
fmt.Println(claims.Subject, claims.OrgID)

// Explicit same-origin Core session -> JWT exchange
token, err := client.ExchangeSessionToken(
ctx,
"https://app.example.com/account",
request.Header.Get("Cookie"),
"/v1/sessions/token",
)
```

## Verify webhook

```go
func webhookHandler(w http.ResponseWriter, r *http.Request) {
event, err := client.VerifyWebhook(r)
if err != nil {
    http.Error(w, "invalid signature", http.StatusBadRequest)
    return
}
// event.Body: raw JSON body
// event.ID:   svix-id for idempotency
w.WriteHeader(http.StatusNoContent)
}
```

## Core API

| Symbol | Description |
| --- | --- |
| `NewClient(opts)` | Construct the client. `Issuer` is required; other fields are optional. |
| `(*Client).VerifyAccessToken(ctx, token)` | Verify a JWT string, return `*Claims` or error. |
| `(*Client).AuthenticateRequest(ctx, r)` | Extract and verify token from an HTTP request. Always returns `AuthState`, does not panic. |
| `(*Client).Middleware(next, onUnauthorized)` | Standard `net/http` middleware. Injects `*Claims` into context on success. |
| `ClaimsFromContext(ctx)` | Extract claims injected by Middleware. |
| `(*Client).VerifyWebhook(r)` | Verify webhook request signature. Returns `*WebhookEvent` with raw body on success. |

## ClientOptions

| Field | Default | Description |
| --- | --- | --- |
| `Issuer` | required | Vonvon issuer URL |
| `Audience` | empty (skip) | Expected JWT aud claim |
| `WebhookSecret` | empty | Webhook HMAC signing secret |
| `JWKSCacheTTL` | `1h` | JWKS local cache TTL |
| `HTTPClient` | 10s timeout default | HTTP client for JWKS fetch |

## Platform notes

- ES256 is the primary algorithm; RS256 is supported for compatibility. ES384 and ES512 are not yet implemented.
- JWKS is fetched from `{issuer}/jwks`. OIDC Discovery auto-detection is a planned improvement.
- `Claims` embeds `jwt.RegisteredClaims` and adds `ClientID`, `Scope`, `AMR`, `ACR`, `OrgID`, `OrgSlug`.

<!-- vonvon-doc-path: /sdks/rust -->
<!-- vonvon-doc-slug: sdks/rust -->
# sdk/rust

> Async Rust server SDK for networkless JWT verification, request authentication, and webhook signature validation.

Locale: en
Canonical: https://vonvon.id/sdks/rust
Markdown: https://vonvon.id/sdks/rust/index.md
Source: https://vonvon.id/sdks/rust/index.mdx

## Status

Implemented and verified locally. Real IdP round-trip verification (JWKS fetch, token sign/verify against a live Vonvon instance) has not been performed yet and must be completed before production use.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Request authentication is Bearer-only by default. An application-owned JWT cookie is read only when its exact name is configured. The opaque \_\_Host-vonvon.rt.\* Core cookie is never scanned or verified locally; exchange it by forwarding the complete Cookie header to exact same-origin POST /v1/sessions/token with redirects disabled, and accept only a response containing the token field.

## Install

Add to `Cargo.toml`:

```toml
[dependencies]
vonvon = { path = "../sdk/rust" }
tokio = { version = "1", features = ["full"] }
```

## Quick start

```rust
use std::sync::Arc;
use vonvon::{VonvonClient, VonvonClientConfig, AuthState};

#[tokio::main]
async fn main() {
let config = VonvonClientConfig::new("https://vonvon.id")
    .with_audience("your-client-id");

let client = Arc::new(VonvonClient::new(config).expect("build client"));

match client.verify_token("eyJ...").await {
    Ok(verified) => {
        println!("user: {}", verified.claims.sub);
        println!("email: {:?}", verified.claims.email);
    }
    Err(e) => eprintln!("invalid token: {e}"),
}
}
```

## Authenticate a request

```rust
let state = client.authenticate_request(raw_headers, cookies).await;

match state {
AuthState::Authenticated(token) => {
    println!("user: {}", token.claims.sub);
    // token.claims.has_scope("openid") -> bool
    // token.claims.org_id -> Option<String>
}
AuthState::Unauthenticated => { /* return 401 */ }
AuthState::Invalid(e) => { /* return 401 */ }
}

let token = client.exchange_session_token(
"https://app.example.com/account",
raw_cookie_header,
Some("/v1/sessions/token"),
).await?;
```

## Verify webhook

```rust
use vonvon::WebhookVerifier;

let webhook_secret =
std::env::var("VONVON_WEBHOOK_SECRET").expect("VONVON_WEBHOOK_SECRET is required");
let verifier = WebhookVerifier::new(&webhook_secret).expect("valid secret");

match verifier.verify_from_headers(headers, body) {
Ok(()) => {
    let payload = vonvon::WebhookPayload::from_bytes(body).unwrap();
    println!("event: {}", payload.event_type);
}
Err(e) => { /* return 400 */ }
}
```

## Core API

| Symbol | Description |
| --- | --- |
| `VonvonClientConfig::new(issuer)` | Minimal constructor. Chain builder methods for optional settings. |
| `.with_audience(aud)` | Set expected audience claim. |
| `.with_session_cookie(name)` | Configure an application-owned JWT cookie name; disabled by default. |
| `.with_leeway(seconds)` | Clock skew tolerance for exp/nbf. |
| `VonvonClient::new(config)` | Build client with default reqwest HTTP client. |
| `VonvonClient::with_http_client(config, http)` | Build client with a custom reqwest client (useful for testing). |
| `client.verify_token(token)` | Verify token string; returns `VonvonResult<VerifiedToken>`. |
| `client.authenticate_request(headers, cookies)` | Extract and verify token from raw headers and cookies; returns `AuthState`. |
| `WebhookVerifier::new(secret)` | Accept `whsec_<base64>` or raw base64 secret. |
| `verifier.verify_from_headers(headers, body)` | Extract svix headers automatically and validate HMAC-SHA256 signature. |

## Platform notes

- Async-first API built on tokio. Uses rustls (no OpenSSL dependency) via reqwest.
- ES256 is the primary algorithm; RS256 is supported. PS256 support is planned. ES384/ES512 are not yet implemented.
- Framework integration features (`axum`, `actix-web`) are planned but not included in this release.
- `VonvonError` uses `thiserror` for structured error variants including `JwtValidation`, `JwksFetch`, `KeyNotFound`, `IssuerMismatch`, and webhook-specific variants.

<!-- vonvon-doc-path: /sdks/python -->
<!-- vonvon-doc-slug: sdks/python -->
# sdk/python

> Async Python server SDK for networkless JWT verification, request authentication, and webhook signature validation.

Locale: en
Canonical: https://vonvon.id/sdks/python
Markdown: https://vonvon.id/sdks/python/index.md
Source: https://vonvon.id/sdks/python/index.mdx

## Status

Implemented and verified locally. Real IdP round-trip verification (JWKS fetch, token sign/verify against a live Vonvon instance) has not been performed yet and must be completed before production use.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Request authentication is Bearer-only by default. An application-owned JWT cookie is read only when its exact name is configured. The opaque \_\_Host-vonvon.rt.\* Core cookie is never scanned or verified locally; exchange it by forwarding the complete Cookie header to exact same-origin POST /v1/sessions/token with redirects disabled, and accept only a response containing the token field.

## Install

```shell
pip install "vonvon @ git+https://github.com/StringKe/vonvon#subdirectory=sdk/python"
```

## Quick start

Construct one `VonvonClient` at startup and reuse it. The client caches JWKS internally.

```python
from vonvon import VonvonClient

client = VonvonClient(
issuer="https://vonvon.id",
audience="https://api.yourapp.com",  # optional
)

# Verify a token
claims = await client.verify_token("eyJ...")
print(claims.sub, claims.email, claims.scope)

# Authenticate a request (Bearer-only by default)
status = await client.authenticate_request(headers=dict(request.headers))
if not status.authenticated:
raise Unauthorized()
user_id = status.claims.sub

# Explicit same-origin Core session -> JWT exchange
token = await client.exchange_session_token(
incoming_request_url="https://app.example.com/account",
cookie_header=request.headers["cookie"],
)
```

## Verify webhook

```python
from vonvon import WebhookVerificationError

try:
webhook = client.verify_webhook(
    payload=request.body,
    headers=dict(request.headers),
    secret="whsec_xxx",
)
import json
event = json.loads(webhook.body)
except WebhookVerificationError as exc:
raise BadRequest(str(exc))
```

## FastAPI integration

```python
from fastapi import FastAPI, Depends, HTTPException, Request
from vonvon import VonvonClient, TokenClaims

app = FastAPI()
vonvon = VonvonClient(issuer="https://vonvon.id")

@app.on_event("shutdown")
async def shutdown():
await vonvon.aclose()

async def require_auth(request: Request) -> TokenClaims:
status = await vonvon.authenticate_request(dict(request.headers))
if not status.authenticated:
    raise HTTPException(status_code=401)
return status.claims

@app.get("/me")
async def me(claims: TokenClaims = Depends(require_auth)):
return {"sub": claims.sub, "email": claims.email}
```

## VonvonClient options

| Parameter | Default | Description |
| --- | --- | --- |
| `issuer` | required | Vonvon issuer URL |
| `audience` | `None` | Expected aud claim; None skips validation |
| `jwks_ttl` | `3600` | JWKS in-memory cache TTL in seconds |
| `http_timeout` | `10.0` | JWKS fetch timeout in seconds |
| `cookie_name` | `disabled` | Application-owned JWT cookie name; disabled unless explicitly configured |
| `leeway` | `0` | Clock skew tolerance in seconds |

## Core API

| Method | Description |
| --- | --- |
| `await client.verify_token(token)` | Verify JWT string; raises `TokenVerificationError` on failure. |
| `await client.authenticate_request(headers, cookies)` | Extract and verify token from headers/cookies. Returns `AuthStatus`; does not raise. |
| `client.verify_webhook(payload, headers, secret)` | Synchronous. Validates svix HMAC-SHA256 + 5-minute replay window. Raises `WebhookVerificationError` on failure. |
| `await client.aclose()` | Release underlying HTTP client resources. |

## Platform notes

- Async-first. Sync callers (Django/Flask) can wrap with `asyncio.run()`.
- Depends on `pyjwt[crypto] >=2.8` and `httpx >=0.27`. Python 3.10+ required.
- Multi-worker deployments share no JWKS cache across processes. A shared cache (Redis) is a planned improvement.

<!-- vonvon-doc-path: /sdks/ruby -->
<!-- vonvon-doc-slug: sdks/ruby -->
# sdk/ruby

> Ruby server SDK for networkless JWT verification, Rack/Rails request authentication, and webhook signature validation.

Locale: en
Canonical: https://vonvon.id/sdks/ruby
Markdown: https://vonvon.id/sdks/ruby/index.md
Source: https://vonvon.id/sdks/ruby/index.mdx

## Status

Implemented and verified locally. Real IdP round-trip verification (JWKS fetch, token sign/verify against a live Vonvon instance) has not been performed yet and must be completed before production use.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Request authentication is Bearer-only by default. An application-owned JWT cookie is read only when its exact name is configured. The opaque \_\_Host-vonvon.rt.\* Core cookie is never scanned or verified locally; exchange it by forwarding the complete Cookie header to exact same-origin POST /v1/sessions/token with redirects disabled, and accept only a response containing the token field.

## Install

```ruby
# Gemfile
gem "vonvon", path: "../vonvon/sdk/ruby"

bundle install
```

## Quick start

```ruby
require "vonvon"

Vonvon.configure do |c|
  c.issuer         = "https://vonvon.id"
  c.audience       = "your_client_id"
  c.webhook_secret = "whsec_AbCdEf..."
end

# Verify a token
begin
  claims = Vonvon.verify_token(raw_token)
  puts claims.sub    # => "usr_abc123"
  puts claims.scope  # => "openid profile email"
rescue Vonvon::TokenVerificationError => e
  puts "Token invalid: #{e.message}"
end
```

## Authenticate a Rack/Rails request

```ruby
# Sinatra before-filter
before do
  auth = Vonvon.authenticate_request(request)
  halt 401, "Unauthorized" unless auth.signed_in?
  @current_user_id = auth.claims.sub
end

# Explicit same-origin Core session -> JWT exchange
token = Vonvon.exchange_session_token(
  incoming_request_url: request.url,
  cookie_header: request.get_header("HTTP_COOKIE")
)
```

## Verify webhook

```ruby
# Rails controller action
def receive
  raw_body = request.raw_post
  payload = Vonvon.verify_webhook(request.headers.to_h, raw_body)
  handle_event(payload["type"], payload["data"])
  head :ok
rescue Vonvon::WebhookVerificationError
  head :bad_request
end
```

## Multi-issuer setup

```ruby
config_a = Vonvon::Configuration.new
config_a.issuer   = "https://tenant-a.vonvon.id"
config_a.audience = "client_a"
client_a = Vonvon::Client.new(config_a)
claims = client_a.verify_token(token)
```

## Configuration options

| Key | Default | Description |
| --- | --- | --- |
| `issuer` | `https://vonvon.id` | OIDC issuer URL |
| `audience` | `nil` | Expected aud claim; nil skips validation |
| `jwks_ttl` | `3600` | JWKS local cache TTL in seconds |
| `leeway` | `60` | JWT clock skew tolerance in seconds |
| `webhook_secret` | `nil` | Webhook signing secret with `whsec_` prefix |
| `webhook_tolerance` | `300` | Webhook replay window in seconds |
| `cookie_name` | `disabled` | Application-owned JWT cookie name; disabled unless explicitly configured |

## Platform notes

- Depends on the `jwt` gem (ES256/RS256 support). Ruby 3.1+ required.
- `Vonvon.authenticate_request` accepts both a Rack env hash and a Rack `Request` object.
- Exception hierarchy: `Vonvon::Error` -&gt; `ConfigurationError`, `JwksError`, `TokenVerificationError`, `WebhookVerificationError`.

<!-- vonvon-doc-path: /sdks/php -->
<!-- vonvon-doc-slug: sdks/php -->
# sdk/php

> PHP 8.1+ server SDK for networkless JWT verification, PSR-7 request authentication, and webhook signature validation.

Locale: en
Canonical: https://vonvon.id/sdks/php
Markdown: https://vonvon.id/sdks/php/index.md
Source: https://vonvon.id/sdks/php/index.mdx

## Status

Implemented and verified locally. Real IdP round-trip verification (JWKS fetch, token sign/verify against a live Vonvon instance) has not been performed yet and must be completed before production use.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Request authentication is Bearer-only by default. An application-owned JWT cookie is read only when its exact name is configured. The opaque \_\_Host-vonvon.rt.\* Core cookie is never scanned or verified locally; exchange it by forwarding the complete Cookie header to exact same-origin POST /v1/sessions/token with redirects disabled, and accept only a response containing the token field.

## Install

PHP 8.1+ required. Core dependencies are pulled automatically by Composer.

```shell
{
  "repositories": [
{ "type": "path", "url": "../vonvon/sdk/php" }
  ],
  "require": {
"vonvon/vonvon": "dev-main"
  }
}

# composer update vonvon/vonvon
```

## Quick start

```php
use Vonvon\VonvonClient;
use Vonvon\Exception\TokenException;
use Vonvon\Exception\JwksException;

$vonvon = new VonvonClient([
'issuer'   => 'https://vonvon.id',
'audience' => 'your-client-id',
'cache'    => $psrSimpleCacheImpl, // PSR-16; null disables JWKS cache
]);

try {
$claims = $vonvon->verifyToken($jwtString);
echo $claims->sub();    // user ID
echo $claims->scope();  // "openid profile email"
echo implode(',', $claims->amr()); // "phr" / "otp"
} catch (TokenException $e) {
http_response_code(401);
} catch (JwksException $e) {
http_response_code(503);
}
```

## Authenticate a PSR-7 request

```php
$result = $vonvon->authenticateRequest($psrRequest);

if ($result->isAuthenticated()) {
$userId = $result->claims()->sub();
} else {
// $result->reason() for server-side logs only
http_response_code(401);
}

$token = $vonvon->exchangeSessionToken(
'https://app.example.com/account',
$psrRequest->getHeaderLine('Cookie'),
$sessionTokenTransport,
);
```

## Verify webhook

```php
use Vonvon\Exception\WebhookException;

try {
$payload = $vonvon->verifyWebhook($psrRequest, 'whsec_...');
$type = $payload->type();  // "user.created"
$data = $payload->data();
} catch (WebhookException $e) {
http_response_code(400);
}
```

## VonvonClient options

| Key | Default | Description |
| --- | --- | --- |
| `issuer` | required | Vonvon issuer URI |
| `audience` | `null` | Expected audience; null skips validation |
| `cache` | `null` | PSR-16 CacheInterface for JWKS caching |
| `jwks_ttl` | `3600` | JWKS cache TTL in seconds |
| `clock_leeway` | `0` | JWT clock skew tolerance in seconds |
| `cookie_name` | `disabled` | Application-owned JWT cookie name; disabled unless explicitly configured |

## VonvonClient methods

| Method | Returns | Description |
| --- | --- | --- |
| `verifyToken(string $token)` | `Claims` | Verify JWT string; throws on failure |
| `authenticateRequest(ServerRequestInterface $request)` | `AuthResult` | Authenticate PSR-7 request; does not throw |
| `verifyWebhook(ServerRequestInterface $request, string $secret)` | `WebhookPayload` | Validate webhook signature; throws on failure |
| `refreshJwks()` | `void` | Force-refresh the JWKS cache |

## Platform notes

- Uses `firebase/php-jwt` for ES256/RS256 verification. HS256 and `none` alg are rejected.
- Requires a PSR-7 request object for `authenticateRequest` and `verifyWebhook`. Convert framework-native requests with a PSR-7 bridge if needed.
- Exception hierarchy: `VonvonException` -&gt; `TokenException`, `JwksException`, `WebhookException`.

<!-- vonvon-doc-path: /sdks/java -->
<!-- vonvon-doc-slug: sdks/java -->
# sdk/java

> Java 17+ server SDK for networkless JWT verification, HTTP request authentication, and webhook signature validation.

Locale: en
Canonical: https://vonvon.id/sdks/java
Markdown: https://vonvon.id/sdks/java/index.md
Source: https://vonvon.id/sdks/java/index.mdx

## Status

Implemented and verified locally. Real IdP round-trip verification (JWKS fetch, token sign/verify against a live Vonvon instance) has not been performed yet and must be completed before production use.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Request authentication is Bearer-only by default. An application-owned JWT cookie is read only when its exact name is configured. The opaque \_\_Host-vonvon.rt.\* Core cookie is never scanned or verified locally; exchange it by forwarding the complete Cookie header to exact same-origin POST /v1/sessions/token with redirects disabled, and accept only a response containing the token field.

## Install

Java 17+ and Maven required.

```xml
<!-- First install the source checkout: cd sdk/java && mvn install -->
<dependency>
  <groupId>dev.vonvon</groupId>
  <artifactId>vonvon-sdk-java</artifactId>
  <version>0.1.0-alpha.0</version>
</dependency>
```

## Quick start

Construct one `VonvonClient` at application startup and use it as a singleton.

```java
import dev.vonvon.sdk.VonvonClient;
import dev.vonvon.sdk.VonvonClientOptions;
import dev.vonvon.sdk.VonvonClaims;
import dev.vonvon.sdk.VonvonTokenException;
import dev.vonvon.sdk.VonvonJwksException;

VonvonClient vonvon = VonvonClient.create(
VonvonClientOptions.builder()
    .issuer("https://vonvon.id")
    .audience("your-client-id")
    .webhookSecret("whsec_xxx")
    .build()
);

try {
VonvonClaims claims = vonvon.verifyToken(accessToken);
String userId = claims.getSub();
String scope  = claims.getScope();
} catch (VonvonTokenException e) {
response.sendError(401, "Unauthorized: " + e.getReason());
} catch (VonvonJwksException e) {
response.sendError(503, "Service unavailable");
}
```

## Authenticate an HTTP request

```java
import dev.vonvon.sdk.AuthResult;

// Bearer-only by default
AuthResult result = vonvon.authenticateRequest(request.getHeader("Authorization"), null);

if (result.isAuthenticated()) {
String userId = result.getClaims().get().getSub();
} else {
response.sendError(401);
}

String token = vonvon.exchangeSessionToken(
request.getRequestURL().toString(),
request.getHeader("Cookie"),
"/v1/sessions/token"
);
```

## Verify webhook

```java
import dev.vonvon.sdk.VonvonWebhookException;

byte[] rawBody = request.getInputStream().readAllBytes();
Map<String, String> headers = Map.of(
"svix-id",        request.getHeader("svix-id"),
"svix-timestamp", request.getHeader("svix-timestamp"),
"svix-signature", request.getHeader("svix-signature")
);

try {
vonvon.verifyWebhook(headers, rawBody);
} catch (VonvonWebhookException e) {
response.sendError(400, "Invalid webhook: " + e.getReason());
}
```

## VonvonClientOptions

| Method | Default | Description |
| --- | --- | --- |
| `.issuer(String)` | required | OIDC issuer; must match token iss exactly |
| `.audience(String)` | `null` | Expected aud; null skips validation |
| `.webhookSecret(String)` | `null` | Webhook secret (`whsec_` prefix or raw base64) |
| `.jwksCacheDuration(Duration)` | 1 hour | JWKS in-memory cache TTL |
| `.clockSkewTolerance(Duration)` | 30 seconds | exp/nbf clock skew tolerance |
| `.connectTimeout(Duration)` | 5 seconds | HTTP connection timeout for JWKS fetch |
| `.readTimeout(Duration)` | 10 seconds | HTTP read timeout for JWKS fetch |

## Platform notes

- Uses `nimbus-jose-jwt` for JWT/JWKS parsing. ES256 is primary; RS256 and PS256 are supported.
- All public APIs are synchronous and thread-safe.
- Logging via SLF4J facade; bring your own implementation (Logback, Log4j2).
- Exception hierarchy: `VonvonException` -&gt; `VonvonTokenException`, `VonvonJwksException`, `VonvonWebhookException`.

<!-- vonvon-doc-path: /sdks/dotnet -->
<!-- vonvon-doc-slug: sdks/dotnet -->
# sdk/dotnet

> .NET 8 server SDK for networkless JWT verification, ASP.NET Core request authentication, and webhook signature validation.

Locale: en
Canonical: https://vonvon.id/sdks/dotnet
Markdown: https://vonvon.id/sdks/dotnet/index.md
Source: https://vonvon.id/sdks/dotnet/index.mdx

## Status

Implemented and verified locally. Real IdP round-trip verification (JWKS fetch, token sign/verify against a live Vonvon instance) has not been performed yet and must be completed before production use.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

Request authentication is Bearer-only by default. An application-owned JWT cookie is read only when its exact name is configured. The opaque \_\_Host-vonvon.rt.\* Core cookie is never scanned or verified locally; exchange it by forwarding the complete Cookie header to exact same-origin POST /v1/sessions/token with redirects disabled, and accept only a response containing the token field.

## Install

.NET 8 target required.

```xml
<ItemGroup>
  <ProjectReference Include="../vonvon/sdk/dotnet/Vonvon.csproj" />
</ItemGroup>
```

## ASP.NET Core setup (recommended)

```csharp
// Program.cs
using Vonvon;

builder.Services.AddVonvon(options =>
{
options.Issuer   = "https://vonvon.id";
options.Audience = "your-client-id"; // optional
});
```

## Authenticate a request

```csharp
// Controller / Minimal API
public class MyController(VonvonClient vonvon) : ControllerBase
{
[HttpGet("/me")]
public async Task<IActionResult> GetMe()
{
    var auth = await vonvon.AuthenticateRequestAsync(
        authorizationHeader: Request.Headers.Authorization);

    if (!auth.Authenticated)
        return Unauthorized(auth.Reason);

    return Ok(new { sub = auth.Claims!.Sub, email = auth.Claims.Email });
}

private Task<string> ExchangeSessionAsync() => vonvon.ExchangeSessionTokenAsync(
    $"{Request.Scheme}://{Request.Host}{Request.Path}",
    Request.Headers.Cookie.ToString());
}
```

## Verify token directly

```csharp
using Vonvon;

var client = new VonvonClient(new VonvonOptions { Issuer = "https://vonvon.id" });

try
{
var claims = await client.VerifyTokenAsync("eyJ...");
Console.WriteLine($"sub={claims.Sub} email={claims.Email}");
}
catch (TokenVerificationException ex)
{
Console.WriteLine($"Invalid token: {ex.Message}");
}
```

## Verify webhook

```csharp
app.MapPost("/webhooks/vonvon", async (HttpRequest req, VonvonClient vonvon) =>
{
using var ms = new MemoryStream();
await req.Body.CopyToAsync(ms);
var body = ms.ToArray();

var headers = new Dictionary<string, string>
{
    ["svix-id"]        = req.Headers["svix-id"].ToString(),
    ["svix-timestamp"] = req.Headers["svix-timestamp"].ToString(),
    ["svix-signature"] = req.Headers["svix-signature"].ToString(),
};

var webhookSecret = Environment.GetEnvironmentVariable("VONVON_WEBHOOK_SECRET")
    ?? throw new InvalidOperationException("VONVON_WEBHOOK_SECRET is required");

try
{
    var webhook = vonvon.VerifyWebhook(body, headers, secret: webhookSecret);
    return Results.Ok();
}
catch (WebhookVerificationException ex)
{
    return Results.BadRequest(ex.Message);
}
});
```

## VonvonOptions

| Property | Default | Description |
| --- | --- | --- |
| `Issuer` | required | Vonvon issuer URL |
| `Audience` | `null` | Expected aud claim; null skips validation |
| `JwksTtl` | 1 hour | JWKS in-memory cache TTL |
| `SessionCookieName` | `disabled` | Application-owned JWT cookie name; disabled unless explicitly configured |
| `ClockSkew` | 5 minutes | JWT exp/nbf clock skew tolerance |
| `WebhookToleranceWindow` | 5 minutes | Webhook replay prevention window |

## VonvonClient API

| Method | Description |
| --- | --- |
| `VerifyTokenAsync(token, ct)` | Verify JWT string; throws `TokenVerificationException` on failure. |
| `AuthenticateRequestAsync(authHeader, cookies, ct)` | Extract and verify token; returns `AuthStatus`; does not throw. |
| `VerifyWebhook(payload, headers, secret)` | Validate webhook signature; throws `WebhookVerificationException` on failure. Synchronous. |

## Platform notes

- Uses `Microsoft.IdentityModel.Tokens` and `System.IdentityModel.Tokens.Jwt` 8.x. ES256 is primary; RS256 and PS256 are supported.
- `AddVonvon()` registers `VonvonClient` as a singleton and wires `IHttpClientFactory` for JWKS fetching.
- Exception hierarchy: `VonvonException` -&gt; `JwksException`, `TokenVerificationException`, `WebhookVerificationException`.

<!-- vonvon-doc-path: /sdks/ios -->
<!-- vonvon-doc-slug: sdks/ios -->
# sdk/ios

> Swift SDK for iOS and macOS using ASWebAuthenticationSession, PKCE S256 authorization code flow, and Keychain token storage.

Locale: en
Canonical: https://vonvon.id/sdks/ios
Markdown: https://vonvon.id/sdks/ios/index.md
Source: https://vonvon.id/sdks/ios/index.mdx

## Status

Package status is **Implemented and verified locally**. The Swift unit-test suite passes on macOS for the iOS package. Simulator or device behavior and a real IdP round-trip on a running Vonvon instance remain pending manual verification. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

## Requirements

- iOS 16+ / macOS 13+
- Swift 5.9+ and Xcode 15+
- No third-party dependencies — uses Apple system frameworks only

## Installation

Add the package via Swift Package Manager in Xcode (File -&gt; Add Package Dependencies) or directly in `Package.swift`:

```swift
// Package.swift
dependencies: [
.package(path: "../vonvon/sdk/ios"),
],
targets: [
.target(name: "YourApp", dependencies: [.product(name: "Vonvon", package: "ios")]),
]
```

## Quick start

```swift
import Vonvon

// 1. Configure in @main App.init. offline_access is rejected until DPoP is implemented.
Vonvon.shared.configure(options: VonvonConfiguration(
issuer: URL(string: "https://vonvon.id")!,
clientId: "your_client_id",
redirectUri: URL(string: "com.example.app://auth/callback")!,
scopes: ["openid", "profile", "email"]
))

// 2. Sign in (opens ASWebAuthenticationSession)
try await Vonvon.shared.signIn()

// 3. Handle redirect in SceneDelegate
let session = try await Vonvon.shared.handleRedirect(url: callbackUrl)

// 4. Read the current unexpired session. Expiry requires reauthorization.
if let session = try await Vonvon.shared.getSession() {
let token = try await Vonvon.shared.getAccessToken()
}

// 5. Clear local state and optionally call end_session.
try await Vonvon.shared.signOut(callEndSession: true)
```

## Core API

| Method | Description |
| --- | --- |
| `configure(options:)` | Initialize with issuer, clientId, redirectUri, scopes. Call before all others. |
| `signIn(options:) async throws` | Open ASWebAuthenticationSession with PKCE S256 authorization URL. Returns when the browser session ends. |
| `handleRedirect(url:) async throws -> VonvonSession` | Validate OAuth state, exchange authorization code at the token endpoint, persist tokens to Keychain, and return a session. |
| `getSession() async throws -> VonvonSession?` | Return the current unexpired iOS session; expired token state is cleared and the method returns nil. |
| `getAccessToken(forceRefresh:) async throws -> String` | Return the current unexpired access token. The SDK rejects offline\_access until DPoP is implemented; expiry requires reauthorization. |
| `signOut(callEndSession:) async throws` | Clear Keychain tokens. Pass true to call the end\_session endpoint via the browser. |
| `setTokenStorage(_:) throws` | Replace the default KeychainTokenStorage with a custom TokenStorageAdapter implementation. |

## Storage adapter

The default storage uses Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` — tokens are not synced to iCloud Keychain. Implement the `TokenStorageAdapter` protocol to use an enterprise Keychain policy:

```swift
struct EnterpriseKeychain: TokenStorageAdapter {
func save(key: String, value: String) throws { /* ... */ }
func load(key: String) throws -> String? { /* ... */ }
func delete(key: String) throws { /* ... */ }
}
try Vonvon.shared.setTokenStorage(EnterpriseKeychain())
```

## Security

- Public client — no client secret stored or transmitted.
- PKCE S256 only. Server rejects plain challenge method.
- Random OAuth state generated per request; validated on redirect to prevent CSRF.
- PKCE code\_verifier written to Keychain only for the duration of the authorization flow and deleted immediately after the code exchange.
- ASWebAuthenticationSession launched with prefersEphemeralWebBrowserSession = true to avoid sharing browser cookies across apps.

## Known limitations

- JWKS-backed ES256/RS256 ID token verification, nonce validation, and end\_session logout are implemented and locally tested. A real IdP round-trip on an iOS device or simulator is still required before L4 support.
- Keychain behavior must be verified in an Xcode device or simulator test run.

<!-- vonvon-doc-path: /sdks/android -->
<!-- vonvon-doc-slug: sdks/android -->
# sdk/android

> Kotlin SDK for Android using Chrome Custom Tabs, PKCE S256 authorization code flow, and Keystore-backed EncryptedSharedPreferences token storage.

Locale: en
Canonical: https://vonvon.id/sdks/android
Markdown: https://vonvon.id/sdks/android/index.md
Source: https://vonvon.id/sdks/android/index.mdx

## Status

Package status is **Implemented and verified locally**. The JVM unit-test suite passes and covers PKCE, state and nonce handling, guest capability, and storage contracts. EncryptedSharedPreferences, Chrome Custom Tabs, App Links, and a real IdP round-trip still require a device or emulator. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

## Requirements

- Android API 26+ (Android 8.0)
- Kotlin 1.9+ and AndroidX

## Installation

Add the dependency to your app module's build.gradle.kts:

```kotlin
// settings.gradle.kts
includeBuild("../vonvon/sdk/android")

// app/build.gradle.kts
dependencies {
implementation("dev.vonvon:vonvon-android:0.1.0-alpha.0")
}
```

## Manifest setup

Register a callback Activity with an intent-filter. App Links (HTTPS scheme with autoVerify) are recommended over custom schemes:

```xml
<!-- AndroidManifest.xml -->
<activity android:name=".AuthCallbackActivity" android:exported="true">
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https"
          android:host="yourapp.example.com"
          android:pathPrefix="/auth/callback" />
</intent-filter>
</activity>
```

## Quick start

```kotlin
import dev.vonvon.sdk.Vonvon
import dev.vonvon.sdk.model.VonvonConfig

// 1. Initialize in Application.onCreate. offline_access is rejected until DPoP is implemented.
Vonvon.configure(
context = this,
config = VonvonConfig(
    issuer = "https://vonvon.id",
    clientId = "your_client_id",
    redirectUri = "https://yourapp.example.com/auth/callback",
    scopes = listOf("openid", "profile", "email"),
)
)

// 2. Sign in (opens Chrome Custom Tabs)
lifecycleScope.launch { Vonvon.signIn(requireContext()) }

// 3. Handle redirect in AuthCallbackActivity
val session = Vonvon.handleRedirect(intent.data.toString())

// 4. Read the current unexpired session. Expiry requires reauthorization.
val session = Vonvon.getSession()

// 5. Get the current unexpired access token.
val token = Vonvon.getAccessToken()

// 6. Clear local state and optionally open end_session.
Vonvon.signOut(context = this, openEndSession = true)
```

## Core API

| Method | Signature |
| --- | --- |
| `configure` | `fun configure(context: Context, config: VonvonConfig)` |
| `signIn` | `suspend fun signIn(context: Context, options: SignInOptions? = null)` |
| `handleRedirect` | `suspend fun handleRedirect(url: String): VonvonSession` |
| `getSession` | `suspend fun getSession(): VonvonSession?` |
| `getAccessToken` | `suspend fun getAccessToken(options: GetAccessTokenOptions? = null): String` |
| `signOut` | `suspend fun signOut(context: Context? = null, openEndSession: Boolean = false)` |
| `setTokenStorage` | `fun setTokenStorage(adapter: TokenStorageAdapter)` |

## Error types

All SDK errors are subtypes of the sealed class VonvonException:

| Subclass | Trigger |
| --- | --- |
| `NotConfigured` | configure() was not called |
| `UserCancelled` | User closed Custom Tabs without completing |
| `StateMismatch` | OAuth state mismatch — possible CSRF |
| `TokenExchangeFailed` | Token endpoint returned an error |
| `TokenValidationFailed` | ID token signature or claims validation failed |
| `NoSession` | Session method called while signed out |

## Security

- Public client — no client secret stored or transmitted.
- PKCE S256 only. Server rejects plain challenge method.
- EncryptedSharedPreferences backed by Android Keystore (AES-256-GCM) protects the token store at rest.
- Random OAuth state generated per request; validated on redirect to prevent CSRF.

## Known limitations

- JWKS-backed ID token verification is implemented and locally unit-tested. Android device or emulator and real IdP validation are still required before L4 support.
- No mechanism to detect when the user closes Custom Tabs without completing authorization.
- Single-account only — the storage layer uses fixed keys.

<!-- vonvon-doc-path: /sdks/flutter -->
<!-- vonvon-doc-slug: sdks/flutter -->
# sdk/flutter

> Dart / Flutter SDK for iOS, Android, and desktop using flutter_web_auth_2, PKCE S256 authorization code flow, and flutter_secure_storage token persistence.

Locale: en
Canonical: https://vonvon.id/sdks/flutter
Markdown: https://vonvon.id/sdks/flutter/index.md
Source: https://vonvon.id/sdks/flutter/index.mdx

## Status

Package status is **Implemented and verified locally**. The Dart and Flutter unit-test suite passes and covers PKCE, nonce and ID token verification, guest capability, session expiry, and storage contracts. Platform-channel paths and a real IdP round-trip still require a device or simulator. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

## Installation

Add to pubspec.yaml and run flutter pub get:

```yaml
# pubspec.yaml
dependencies:
  vonvon:
git:
  url: https://github.com/StringKe/vonvon
  path: sdk/flutter
  ref: main
```

## Platform setup

Register the callback URI scheme on each platform.

```xml
<!-- Android: AndroidManifest.xml (main Activity) -->
<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="com.example.myapp" android:host="auth" />
</intent-filter>

<!-- iOS: Info.plist -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
<key>CFBundleURLSchemes</key>
<array><string>com.example.myapp</string></array>
  </dict>
</array>
```

## Quick start

```dart
import 'package:vonvon/vonvon.dart';

final client = VonvonClient();

// 1. Initialize (fetches OIDC discovery). offline_access is rejected until DPoP is implemented.
await client.configure(
  const VonvonOptions(
issuer: 'https://vonvon.id',
clientId: 'YOUR_CLIENT_ID',
redirectUri: 'com.example.myapp://auth/callback',
scopes: ['openid', 'profile', 'email'],
  ),
);

// 2. Sign in (opens system browser, PKCE S256)
final session = await client.signIn();
print(session.user.email);

// 3. Get the current unexpired access token. Expiry requires reauthorization.
final token = await client.getAccessToken();

// 4. Get the current unexpired session.
final current = await client.getSession();

// 5. Clear secure storage and optionally open end_session. No revoke request is sent.
await client.signOut();
```

## Core API

| Method | Description |
| --- | --- |
| `configure(VonvonOptions, {storageAdapter?})` | Initialize SDK and fetch OIDC discovery. Must be called before all other methods. |
| `signIn({}additionalParameters?, audience?})` | Open system browser with PKCE S256 authorization URL; exchange code and return VonvonSession. |
| `handleRedirect(String url)` | Process App Link or custom scheme callback. Called internally by signIn; invoke manually for cross-process redirect recovery. |
| `getSession()` | Return the current unexpired VonvonSession, or null after clearing expired local state. |
| `getAccessToken({}bool forceRefresh})` | Return the current unexpired access token. forceRefresh: true clears the session and requires reauthorization. |
| `signOut({}bool openLogoutUrl})` | Clear secure storage and optionally open end\_session\_endpoint in the system browser; no revoke request is sent. |
| `setTokenStorage(TokenStorageAdapter)` | Replace the default SecureStorageAdapter (flutter\_secure\_storage) with a custom implementation. |

## Dependencies

| Package | Version | Purpose |
| --- | --- | --- |
| `flutter_web_auth_2` | ^4.0.0 | System browser authorization session and callback receipt |
| `flutter_secure_storage` | ^9.2.4 | Platform secure storage (Keychain / Keystore / DPAPI) |
| `crypto` | ^3.0.3 | SHA-256 for PKCE S256 challenge computation |
| `http` | ^1.2.2 | HTTP client for discovery and token endpoints |

## Security

- Public client — no client secret stored or transmitted.
- PKCE S256 only. No implicit flow or password grant.
- OAuth state generated per request; validated in handleRedirect to prevent CSRF.
- New sessions store access and ID tokens in platform secure storage. The refreshToken compatibility field remains null, and offline\_access is rejected until DPoP is implemented.

## Known limitations

- JWKS-backed ES256 ID token verification, nonce validation, and persisted state-keyed PKCE are implemented and locally tested. Real device and IdP validation are still required before L4 support.
- offline\_access is rejected until the SDK implements DPoP sender binding; access-token expiry requires reauthorization.

<!-- vonvon-doc-path: /sdks/macos -->
<!-- vonvon-doc-slug: sdks/macos -->
# sdk/macos

> Swift SDK for macOS using ASWebAuthenticationSession, PKCE S256 authorization code flow, and Keychain token storage. Shares the implementation pattern with sdk/ios.

Locale: en
Canonical: https://vonvon.id/sdks/macos
Markdown: https://vonvon.id/sdks/macos/index.md
Source: https://vonvon.id/sdks/macos/index.mdx

## Status

Package status is **Implemented and verified locally**. The Swift unit-test suite passes on macOS. Keychain access, the complete ASWebAuthenticationSession callback, and a real IdP round-trip still require desktop integration evidence. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

## Requirements

- macOS 13+
- Swift 5.9+ and Xcode 15+
- No third-party dependencies — uses Apple system frameworks (AuthenticationServices, CryptoKit, Security)

## Installation

Add via Swift Package Manager in Package.swift:

```swift
// Package.swift
dependencies: [
.package(path: "../vonvon/sdk/macos"),
],
targets: [
.target(name: "YourApp", dependencies: [.product(name: "Vonvon", package: "macos")]),
]
```

## Quick start

```swift
import Vonvon

let client = VonvonClient()

// 1. Configure. offline_access is rejected until DPoP is implemented.
client.configure(VonvonOptions(
issuer: URL(string: "https://vonvon.id")!,
clientId: "your_client_id",
redirectUri: "yourapp://callback"
))

// 2. Sign in (opens ASWebAuthenticationSession)
let session = try await client.signIn()

// 3. Get the current unexpired access token. Expiry requires reauthorization.
let token = try await client.getAccessToken()

// 4. Get the current unexpired session.
let current = try await client.getSession()

// 5. Clear local state and optionally call end_session.
try await client.signOut()
```

## Core API

| Method | Description |
| --- | --- |
| `configure(_ options:)` | Set issuer, clientId, redirectUri, and scopes. Call before all other methods. |
| `signIn() async throws -> VonvonSession` | Launch ASWebAuthenticationSession, complete PKCE S256 authorization code flow, persist tokens to Keychain, and return a session. |
| `handleRedirect(_ url:) async throws -> VonvonSession` | Process a redirect URL from an external source and exchange the code for tokens. |
| `getSession() async throws -> VonvonSession?` | Return the current unexpired macOS session; expired token state is cleared and the method returns nil. |
| `getAccessToken() async throws -> String` | Return the current unexpired access token. The SDK rejects offline\_access until DPoP is implemented; expiry requires reauthorization. |
| `signOut() async throws` | Clear Keychain tokens and optionally call the end\_session endpoint; no refresh-token revocation is performed. |

## Relationship to sdk/ios

The macOS SDK shares the same Swift implementation pattern as sdk/ios — ASWebAuthenticationSession for browser-based authorization, CryptoKit for PKCE S256, and Keychain for token storage. The two packages target different Apple platform minima and are maintained separately to allow platform-specific entitlement configuration.

## Security

- Public client — no client secret stored or transmitted.
- PKCE S256 only. Server rejects plain challenge method.
- OAuth state generated per request; validated on redirect to prevent CSRF.
- Tokens stored in Keychain with device-only access; not synced to iCloud Keychain.

## Known limitations

- JWKS-backed ES256/RS256 ID token verification and end\_session logout are implemented and locally tested. Real macOS Keychain and IdP round-trip validation is still required before L4 support.
- Shared Swift core extraction with sdk/ios is planned but not yet done — each package carries its own copy of the implementation.

<!-- vonvon-doc-path: /sdks/windows -->
<!-- vonvon-doc-slug: sdks/windows -->
# sdk/windows

> C# / .NET SDK for WinUI 3 applications using WebView2 for authorization, PKCE S256, and DPAPI-protected IsolatedStorage for token persistence.

Locale: en
Canonical: https://vonvon.id/sdks/windows
Markdown: https://vonvon.id/sdks/windows/index.md
Source: https://vonvon.id/sdks/windows/index.mdx

## Status

Package status is **Implemented and verified locally**. The cross-platform .NET unit-test suite passes. WebView2, DPAPI, WinUI 3, and a real IdP round-trip still require a Windows integration environment. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

## Requirements

- .NET 8 and Windows App SDK 1.6+
- WebView2 Runtime (Evergreen — pre-installed with Microsoft Edge)
- Application must set &lt;UseWinUI&gt;true&lt;/UseWinUI&gt; in the project file

## Installation

Add a ProjectReference to the source checkout from your application project file:

```xml
<ItemGroup>
  <ProjectReference Include="../vonvon/sdk/windows/Vonvon.Windows.csproj" />
</ItemGroup>
```

## Quick start

```csharp
using Vonvon.Windows;

// 1. Configure in App.xaml.cs OnLaunched.
VonvonClient.Shared.Configure(new VonvonConfiguration
{
Issuer      = new Uri("https://vonvon.id"),
ClientId    = "your_client_id",
RedirectUri = "com.example.myapp://auth/callback",
// Scopes default: openid profile email. offline_access is rejected until DPoP is implemented.
});

// 2. Sign in (opens embedded WebView2 window)
VonvonSession session = await VonvonClient.Shared.SignInAsync();
Console.WriteLine($"Signed in: {session.User.Email}");

// 3. Get the current unexpired access token. Expiry requires reauthorization.
string? token = await VonvonClient.Shared.GetAccessToken();

// 4. Get the current unexpired session.
VonvonSession? current = await VonvonClient.Shared.GetSession();

// 5. Clear local state.
await VonvonClient.Shared.SignOut();
```

## Custom URI scheme callback (optional)

If using a custom URI scheme redirect rather than the WebView2 embedded window, forward the protocol activation URI to `HandleRedirectAsync`:

```csharp
// App.xaml.cs
protected override void OnActivated(IActivatedEventArgs args)
{
if (args.Kind == ActivationKind.Protocol)
{
    var protocolArgs = (ProtocolActivatedEventArgs)args;
    await VonvonClient.Shared.HandleRedirectAsync(protocolArgs.Uri);
}
}
```

## Core API

| Method | Description |
| --- | --- |
| `Configure(VonvonConfiguration)` | Initialize SDK. Call once at application startup. |
| `SignInAsync(options?, ct)` | Open an embedded WebView2 authorization window with PKCE S256. Returns VonvonSession on completion. |
| `HandleRedirectAsync(Uri, ct)` | Process a custom URI scheme callback and exchange the authorization code. |
| `GetSession(ct)` | Return the current unexpired session, clearing expired local state and returning null. |
| `GetAccessToken(options?, ct)` | Return the current unexpired access token; ForceRefresh clears the session and requires reauthorization. |
| `SignOut(ct)` | Clear local session tokens from DPAPI-protected IsolatedStorage. |
| `SetTokenStorage(ITokenStorage)` | Replace the default DpapiTokenStorage with a custom ITokenStorage implementation. |

## Storage adapter

The default storage encrypts tokens with DPAPI (CurrentUser scope) and persists them in IsolatedStorage. Implement `ITokenStorage` to use Windows Hello or Credential Manager:

```csharp
public sealed class MyCustomStorage : ITokenStorage
{
public Task SaveAsync(StoredTokenSet tokens, CancellationToken ct = default) { ... }
public Task<StoredTokenSet?> LoadAsync(CancellationToken ct = default) { ... }
public Task ClearAsync(CancellationToken ct = default) { ... }
}
VonvonClient.Shared.SetTokenStorage(new MyCustomStorage());
```

## Dependencies

| Package | Version | Purpose |
| --- | --- | --- |
| `Microsoft.WindowsAppSDK` | 1.6.250228002 | WinUI 3 host and WebView2 embedding |
| `Microsoft.Web.WebView2` | 1.0.3065.39 | Chromium-based embedded authorization window |
| `System.Security.Cryptography.ProtectedData` | 8.0.0 | DPAPI token encryption at rest |

## Security

- Public client — no client secret stored or transmitted.
- PKCE S256 only. Server rejects plain challenge method.
- Tokens encrypted with DPAPI (CurrentUser scope) and stored in IsolatedStorage. Not accessible to other Windows user accounts.
- OAuth state generated per request; validated on redirect to prevent CSRF.

## Known limitations

- WebView2 Runtime must be present. WebAuthenticationBroker support as a fallback is planned but not yet implemented.
- JWKS-backed ID token verification and end\_session sign-out are implemented and locally tested. Real Windows WebView2, DPAPI, and IdP round-trip validation is still required before L4 support.
- DpapiTokenStorage does not run on non-Windows platforms. Use a different ITokenStorage implementation when cross-compiling.

<!-- vonvon-doc-path: /sdks/linux -->
<!-- vonvon-doc-slug: sdks/linux -->
# sdk/linux

> Rust SDK for Linux desktop using xdg-open for browser launch, loopback TCP for the authorization callback, PKCE S256, and freedesktop.org Secret Service token storage.

Locale: en
Canonical: https://vonvon.id/sdks/linux
Markdown: https://vonvon.id/sdks/linux/index.md
Source: https://vonvon.id/sdks/linux/index.mdx

## Status

Package status is **Implemented and verified locally**. The Rust unit-test suite passes. Secret Service D-Bus storage, xdg-open, the complete loopback callback, and a real IdP round-trip still require a desktop Linux integration environment. This page documents implemented behavior; it is not a production-readiness claim.

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

## Requirements

- Rust (stable, 2021 edition)
- tokio async runtime
- Desktop Linux with xdg-open (xdg-utils) for system browser launch and a running D-Bus session with gnome-keyring or kwallet for Secret Service storage
- Headless / CI environments: use the in-memory-storage feature or inject InMemoryStorage directly

## Installation

Add vonvon-linux to Cargo.toml:

```toml
[dependencies]
vonvon-linux = { path = "../vonvon/sdk/linux" }
tokio = { version = "1", features = ["full"] }
```

## Quick start

```rust
use vonvon_linux::{VonvonClient, VonvonConfigBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
// 1. Build config. offline_access is rejected until DPoP is implemented.
let config = VonvonConfigBuilder::new()
    .issuer("https://vonvon.id")
    .client_id("your_client_id")
    .redirect_uri("http://127.0.0.1:51234/callback")
    .redirect_port(51234)
    .build()?;

// 2. Create client (default: Secret Service storage)
let client = VonvonClient::configure(config)?;

// 3. Sign in. xdg-open launches the browser and loopback TCP receives the callback.
let session = client.sign_in(None).await?;
println!("user: {}", session.user.sub);

// 4. Get the current unexpired access token. Expiry returns SessionExpired.
let token = client.get_access_token(None).await?;

// 5. Clear local token and guest state. No revoke request is sent.
client.sign_out().await?;
Ok(())
}
```

## Headless / CI usage

When no D-Bus Secret Service daemon is available, pass InMemoryStorage to avoid a runtime error:

```rust
use vonvon_linux::{VonvonClient, VonvonConfigBuilder};
use vonvon_linux::storage::InMemoryStorage;
use std::sync::Arc;

let config = VonvonConfigBuilder::new()
.issuer("https://vonvon.id")
.client_id("your_client_id")
.redirect_uri("http://127.0.0.1:51234/callback")
.build()?;

let client = VonvonClient::configure_with_storage(config, Arc::new(InMemoryStorage::new()))?;
```

## Core API

| Method | Description |
| --- | --- |
| `VonvonConfigBuilder::new()` | Builder for VonvonConfig. Required fields: issuer, client\_id, redirect\_uri. Optional: scopes, redirect\_port (default 51234), http\_timeout\_secs (default 30). |
| `VonvonClient::configure(config)` | Create client with default SecretServiceStorage. |
| `VonvonClient::configure_with_storage(config, adapter)` | Create client with a custom StorageAdapter (e.g. InMemoryStorage). |
| `sign_in(options) async` | Open xdg-open browser, start loopback TCP listener on redirect\_port, wait for the authorization code callback, exchange it, store tokens, and return a Session. |
| `get_session() async` | Return the current unexpired stored session; expiry clears local token state and returns SessionExpired. |
| `get_access_token(options) async` | Return the current unexpired access token; expiry or force\_refresh clears local token state and returns SessionExpired. |
| `sign_out() async` | Clear local token and guest session storage; no revoke request is sent. |
| `set_token_storage(adapter)` | Replace the storage adapter after construction. |

## Storage adapters

| Adapter | Description |
| --- | --- |
| `SecretServiceStorage` | Default. Stores tokens in the freedesktop.org Secret Service (gnome-keyring or kwallet) via D-Bus. Requires a running desktop session. |
| `InMemoryStorage` | In-process memory only. Tokens are lost on process exit. Use for testing or CI environments without a Secret Service. |

## Security

- Public client — no client secret stored or transmitted.
- PKCE S256 only. Server rejects plain challenge method.
- OAuth state validated on the loopback callback to prevent CSRF (RFC 8252 loopback redirect).
- Secret Service encrypts tokens at rest via the desktop keyring daemon — the app does not manage encryption keys directly.
- The SDK rejects offline\_access until DPoP is implemented; unexpected refresh\_token response fields are not persisted.

## Known limitations

- JWKS-backed ID token verification, nonce validation, and JWKS cache renewal are implemented and locally tested. A desktop Secret Service and real IdP round-trip are still required before L4 support.
- The redirect port is fixed and must match the redirect\_uri registered in the Vonvon console. Dynamic port randomization (RFC 8252) requires dynamic client registration support.
- System browser redirect and Secret Service storage require desktop environment evidence.

<!-- vonvon-doc-path: /self-hosting -->
<!-- vonvon-doc-slug: self-hosting -->
# Self-hosting

> Deploy Vonvon as three isolated Workers on your Cloudflare account, with the complete data, queue, consistency, email, routing, and production-control inventory.

Locale: en
Canonical: https://vonvon.id/self-hosting
Markdown: https://vonvon.id/self-hosting/index.md
Source: https://vonvon.id/self-hosting/index.mdx

## Required bindings

| Binding | Purpose |
| --- | --- |
| `vonvon-site, vonvon-console, vonvon` | Deploy three Workers: Nimbus Site owns the apex documentation and www redirect, Console owns /dash, and Core owns Hosted Auth, protocols, APIs, jobs, and identity state. Site and Console bind only ASSETS. |
| `DB, CACHE, STORAGE` | Core uses Neon Postgres for tenant-scoped relational data, KV only for read-heavy caches, and R2 for private objects. Strongly consistent state never belongs in KV. |
| `EMAIL, ANALYTICS, SITE_WORKER, CONSOLE_WORKER, ASSETS` | Core binds Email Service and Analytics Engine, plus one-way Service Bindings to Site and Console for exact-route query fallback. Frontend Workers never bind back to Core. |
| `SESSION_REVOCATION, WEBAUTHN_CHALLENGE, OAUTH_STATE, PAR_STORE, DEVICE_FLOW, RATE_LIMITER, AUDIT_SEQ, METERING, GUEST_STORE, CIBA_STATE, IMPERSONATION_GRANTS` | Eleven SQLite-backed Durable Objects serialize sessions, challenges, OAuth, PAR, device and CIBA state, rate limits, audit order, metering, guests, and impersonation grants. |
| `vonvon-email, vonvon-whatsapp, vonvon-sms, vonvon-audit, vonvon-webhook, vonvon-metering, vonvon-scim-sync, vonvon-privacy` | Eight source Queues move email, WhatsApp, SMS, audit, webhook, metering, outbound SCIM, and privacy work off authentication paths. |
| `8 source DLQs + 8 persistence-failure Queues` | Each source Queue requires its own dead-letter Queue and persistence-failure quarantine, for 24 Queues total. The shared vonvon-dlq is obsolete and must not be used. |

## Production configuration

| Secret | Purpose |
| --- | --- |
| `KEK, PEPPER, BOOTSTRAP_TOKEN` | Production and staging require KEK, PEPPER, and BOOTSTRAP\_TOKEN as Workers Secrets. Never place them in variables, the database, source files, or build logs. |
| `EMAIL_FROM_ADDRESS, EMAIL_FROM_NAME` | Set the non-secret sender identity explicitly. Vonvon validates the address and fails closed. Arbitrary-recipient Email Sending requires Workers Paid; Neon Postgres, SQLite-backed Durable Objects, and Queues are available within their free-tier limits. |
| `TURNSTILE_SITE_KEY + TURNSTILE_SECRET; CLOUDFLARE_FOR_SAAS_*` | Configure Turnstile as a complete site-key and secret pair. Optional Cloudflare for SaaS hostnames require a zone, API token, active fallback origin, DNS, and routes. Zone WAF and edge rate limiting remain separate controls; application limits fail closed in RATE\_LIMITER. |

## Deployment checks

Before declaring production ready, reconcile all 24 Queues, apply Neon migrations, build all three Workers, and verify apex, www, wildcard DNS, health, discovery, JWKS, and Hosted Auth. Then record live evidence for Email, DLQ replay, privacy export and 30-day erasure, hourly and daily Cron, Analytics, Turnstile, and custom hostnames. Local L0-L3 evidence is not L4; every unrun live check is UNKNOWN. The full operator runbook is maintained at https://github.com/StringKe/vonvon/blob/main/docs/deployment.md.

```shell
pnpm install
pnpm run cloudflare:queues:plan
pnpm run cloudflare:queues:create
pnpm run cloudflare:queues:check
pnpm check
pnpm test
pnpm build
pnpm smoke:l2-l3
pnpm smoke:three-workers

# Merge a reviewed, signed commit to main so Cloudflare Workers Builds deploys all three Workers.
curl https://<your-domain>/v1/health
curl https://<your-domain>/.well-known/openid-configuration
curl https://<your-domain>/jwks
curl https://<your-domain>/auth/config
curl -I https://www.<your-domain>/
```

<!-- vonvon-doc-path: /status -->
<!-- vonvon-doc-slug: status -->
# Status

> Live service health and timestamped incident updates from Vonvon Core.

Locale: en
Canonical: https://vonvon.id/status
Markdown: https://vonvon.id/status/index.md
Source: https://vonvon.id/status/index.mdx

The HTML status page reads the current incident ledger from the public Core endpoint.

Machine-readable status: https://vonvon.id/v1/public/status