# Wolin (月印千江) — Complete Zero-Hallucination Developer Reference (`llms-full.txt`) > Canonical Reference URL: `https://wolin.id/llms-full.txt` > Concise Index: `https://wolin.id/llms.txt` > Docs MCP Endpoint: `https://wolin.id/mcp` > Copy-Paste Prompt Hub: `https://wolin.id/prompts.html` > Standards: W3C Solid Protocol 0.11 · W3C Solid-OIDC · RFC 9449 DPoP (`ES256`) · RFC 7638 JWK Thumbprint · W3C RDF 1.1 Turtle / JSON-LD · WAC & ACP --- ## 0. Architecture & Core Endpoints at a Glance - **Canonical Solid-OIDC Issuer**: `https://auth.wolin.id` (Discovery: `https://auth.wolin.id/.well-known/openid-configuration`) - **User WebID Format**: `https://{handle}.wolin.id/profile/card#me` - **User Sovereign Pod Root (`pim:storage`)**: `https://{handle}.wolin.id/` (origin-isolated subdomain) or `https://pod.wolin.cloud/{handle}/` - **Wolin Passport Showcase**: Navigating a browser (`Accept: text/html`) to `https://{handle}.wolin.id` renders the user's 3D avatar card and world links; querying with `Accept: text/turtle` returns the standard W3C WebID RDF profile. - **Zero Backend Required for Worlds**: Static web worlds (Vite / Next.js / React Three Fiber / Unity WebGL) deploy for `$0/mo` on Cloudflare Pages. Authentication uses a static `client-id.jsonld` file, and persistent state lives inside each player's Wolin Pod. --- ## 1. 5-Language SDK 10-Line Quickstarts All 5 official Wolin SDKs implement RFC 9449 `ES256` (NIST P-256) DPoP proof signing, RFC 7638 `cnf.jkt` thumbprints, automatic `DPoP-Nonce` retry, W3C WebID `pim:storage` discovery, and `ETag` (`If-Match` / `If-None-Match`) optimistic concurrency with **zero third-party cryptography bloat**. ### 1.1 TypeScript / JavaScript (`@wolin-id/client` & `@wolin-id/react`) - **Repo**: `https://github.com/wolin-id/sdk-js` - **Install**: `pnpm add @wolin-id/client @wolin-id/react` ```ts import { WolinPodClient, fetchWebIdProfile, generateDPoPKeyPair } from '@wolin-id/client'; const profile = await fetchWebIdProfile('https://alice.wolin.id/profile/card#me'); const dpopKeyPair = await generateDPoPKeyPair(); // Web Crypto non-extractable P-256 const pod = new WolinPodClient({ podUrl: profile.primaryStorage, webId: profile.webId, accessToken: tokens.accessToken, // DPoP-bound token from exchangeCodeForTokens() dpopKeyPair, }); const current = await pod.getResource('/private/notes.ttl'); await pod.putResource('/private/notes.ttl', '<#n1> "Alice" .', { ifMatch: current.etag ?? undefined, }); ``` **React 18 / 19 Hook Quickstart (`@wolin-id/react`)**: ```tsx import { WolinProvider, usePodResource, useWolinSession } from '@wolin-id/react'; export const App = () => ( ); function WorldHud() { const { isAuthenticated, session, login, logout } = useWolinSession(); const { data, save } = usePodResource(isAuthenticated ? '/private/world-save.ttl' : null); return isAuthenticated ? : ; } ``` ### 1.2 Unity C# (`id.wolin.unity` — Unity 2022.3+ / `.NET Standard 2.1`) - **Repo**: `https://github.com/wolin-id/sdk-unity` - **Install (`Packages/manifest.json`)**: `"id.wolin.unity": "https://github.com/wolin-id/sdk-unity.git#v0.1.0"` ```csharp using System; using System.Threading.Tasks; using Wolin.Unity; using var client = new WolinClient(); client.SetAccessToken(accessToken, "https://alice.wolin.id/profile/card#me"); Uri storageRoot = await client.DiscoverStorageAsync("https://alice.wolin.id/profile/card#me"); Uri saveUri = new Uri(storageRoot, "games/indie-lobby/save.ttl"); PodResource loaded = await client.GetAsync(saveUri); await client.PutAsync(saveUri, "<#player> 7 .", "text/turtle", ifMatch: loaded.ETag); ``` ### 1.3 Swift 6 (`WolinKit` — iOS 16+ / macOS 13+ / visionOS 1+) - **Repo**: `https://github.com/wolin-id/sdk-swift` - **Install (`Package.swift`)**: `.package(url: "https://github.com/wolin-id/sdk-swift.git", from: "0.1.0")` (`product: "WolinKit"`) ```swift import CryptoKit import WolinKit let signer = DPoPSigner(privateKey: P256.Signing.PrivateKey()) let client = WolinClient(accessToken: token, webID: "https://alice.wolin.id/profile/card#me", dpopSigner: signer) let storageURL = try await client.discoverStorage() let noteURL = storageURL.appending(path: "private/notes.ttl") let resource = try await client.getResource(at: noteURL) if let etag = resource.etag { try await client.putTurtle(at: noteURL, turtle: "<#me> \"Alice\" .", etagMatch: .ifMatch(etag)) } ``` ### 1.4 Kotlin / Android / JVM (`id.wolin:sdk-kotlin` — Kotlin 2.1+ / JVM 17+) - **Repo**: `https://github.com/wolin-id/sdk-kotlin` - **Install (`build.gradle.kts`)**: `implementation("id.wolin:sdk-kotlin:0.1.0")` ```kotlin import id.wolin.sdk.DPoPSigner import id.wolin.sdk.WolinClient val signer = DPoPSigner.generate() val client = WolinClient(accessToken = token, dpopSigner = signer) val storageRoot = client.discoverStorage("https://alice.wolin.id/profile/card#me") val noteUrl = client.resolveResourceUrl(storageRoot, "private/notes.ttl") val current = client.get(noteUrl) client.put(url = noteUrl, body = "<#it> \"Alice\" .", ifMatch = current.etag) ``` ### 1.5 Python 3.11+ (`wolin-id` — Async `httpx`) - **Repo**: `https://github.com/wolin-id/sdk-python` - **Install**: `pip install wolin-id` ```python import os from wolin_id import DpopSigner, WolinClient async def sync_pod() -> None: async with WolinClient("https://pod.wolin.cloud", access_token=os.environ["WOLIN_ACCESS_TOKEN"], dpop_signer=DpopSigner.generate()) as client: profile = await client.fetch_webid_profile("https://alice.wolin.id/profile/card#me") note_url = f"{profile.primary_storage}private/note.ttl" res = await client.get(note_url) await client.put(note_url, '<#it> "Alice" .\n', content_type="text/turtle", if_match=res.etag) ``` --- ## 2. Solid-OIDC Client ID Document (`client-id.jsonld`) — Zero App Review Wolin eliminates OAuth client secrets, developer portal registration, and manual app review. Host this static JSON-LD file at `https:///client-id.jsonld` (`public/client-id.jsonld` in Vite / Next.js) and pass its full URL as `clientId`. ### Copy-Paste `public/client-id.jsonld` ```json { "@context": "https://www.w3.org/ns/solid/oidc-context.jsonld", "client_id": "https://world.example.com/client-id.jsonld", "client_name": "My Wolin 3D World", "client_uri": "https://world.example.com", "logo_uri": "https://world.example.com/icon-192.png", "redirect_uris": [ "https://world.example.com/auth/callback" ], "post_logout_redirect_uris": [ "https://world.example.com/" ], "grant_types": [ "authorization_code", "refresh_token" ], "response_types": [ "code" ], "token_endpoint_auth_method": "none", "scope": "openid webid offline_access" } ``` ### Mandatory `client-id.jsonld` Invariants 1. **Strict Origin Binding**: `new URL(client_id).origin` **MUST** equal `new URL(redirect_uri).origin`. Cross-origin `redirect_uri` values are rejected by `https://auth.wolin.id/authorize` with `invalid_request` to prevent client spoofing. 2. **PKCE `S256` Required**: `code_challenge_method=S256` and `response_type=code` are mandatory (`token_endpoint_auth_method: "none"`). 3. **CORS & Content-Type (`public/_headers` on Cloudflare Pages)**: ```text /client-id.jsonld Content-Type: application/ld+json; charset=utf-8 Access-Control-Allow-Origin: * ``` 4. **Local Development**: During local dev (`http://localhost:5173`), serve `/client-id.jsonld` dynamically or from `public/` with `"client_id": "http://localhost:5173/client-id.jsonld"` and `"redirect_uris": ["http://localhost:5173/auth/callback"]`. --- ## 3. Official Metaverse & Passport RDF Vocabulary (`https://wolin.id/ns#`) All cross-world Wolin apps share the canonical `https://wolin.id/ns#` (`PREFIX wolin: `) vocabulary alongside W3C `foaf:`, `pim:`, `solid:`, `ldp:`, and `schema:`. Do **not** invent ad-hoc avatar predicates; use these exact IRIs so avatars and wearables travel seamlessly across every Wolin-enabled world. ### 3.1 Core Predicates & Classes | Term (`wolin:*`) | Full IRI | Range / Type | Purpose | | :--- | :--- | :--- | :--- | | `wolin:displayName` | `https://wolin.id/ns#displayName` | `xsd:string` | Canonical cross-world 3D nametag & Passport display name (falls back to `foaf:name`). | | `wolin:avatarGlbUrl` | `https://wolin.id/ns#avatarGlbUrl` | `xsd:anyURI` | glTF 2.0 binary (`.glb`) 3D avatar URL for Three.js / R3F / Unity / Vision Pro worlds. | | `wolin:avatarVrmUrl` | `https://wolin.id/ns#avatarVrmUrl` | `xsd:anyURI` | VRM 0.x / 1.0 (`.vrm`) humanoid avatar URL with blendshapes & spring bones for VTuber worlds. | | `wolin:worldLinks` | `https://wolin.id/ns#worldLinks` | `wolin:WorldLink` | Links a user's WebID (`#me`) to favorite or hosted 3D worlds & social portals shown on Wolin Passport. | | `wolin:wearableItem` | `https://wolin.id/ns#wearableItem` | `wolin:Wearable` | Links `#me` or `/public/inventory.ttl` to portable 3D wearable items owned/equipped by the user. | | `wolin:passportTheme` | `https://wolin.id/ns#passportTheme` | `xsd:string` | Optional Passport theme / accent token (e.g. `"cobalt-220"`). | **Supporting `wolin:WorldLink` & `wolin:Wearable` Properties**: - On `wolin:WorldLink`: `schema:name` (`xsd:string`), `schema:url` (`xsd:anyURI`, `http:`/`https:` only), `wolin:linkKind` (`"world"` or `"social"`). - On `wolin:Wearable`: `schema:name` (`xsd:string`), `wolin:assetGlbUrl` (`xsd:anyURI`), `wolin:slot` (`"hat"` | `"accessory"` | `"outfit"` | `"companion"`), `wolin:equipped` (`xsd:boolean`). ### 3.2 Canonical WebID Profile Turtle Example (`/profile/card`) ```turtle @prefix foaf: . @prefix pim: . @prefix solid: . @prefix ldp: . @prefix schema: . @prefix xsd: . @prefix wolin: . <> a foaf:PersonalProfileDocument ; foaf:maker <#me> ; foaf:primaryTopic <#me> . <#me> a foaf:Person ; foaf:name "Alice Kim" ; wolin:displayName "Alice" ; solid:oidcIssuer ; pim:storage ; ldp:inbox ; wolin:passportTheme "cobalt-220" ; wolin:avatarGlbUrl ; wolin:avatarVrmUrl ; wolin:worldLinks <#link-cat-cafe>, <#link-concert> ; wolin:wearableItem <#item-beret> . <#link-cat-cafe> a wolin:WorldLink ; schema:name "Alice's Cozy Cat Cafe" ; schema:url ; wolin:linkKind "world" . <#link-concert> a wolin:WorldLink ; schema:name "Friday VTuber Stage" ; schema:url ; wolin:linkKind "world" . <#item-beret> a wolin:Wearable ; schema:name "Cobalt Artist Beret" ; wolin:assetGlbUrl ; wolin:slot "hat" ; wolin:equipped true . ``` --- ## 4. The 4 Metaverse Lego Blocks Scaffold all 4 blocks together with `pnpm create wolin-world my-world` (`https://github.com/wolin-id/metaverse-starter`), or compose them individually in any Three.js / React Three Fiber app. ### Block 1: Passwordless Login + Portable GLB / VRM Avatar Spawn Dereference the signed-in player's WebID profile, extract `wolin:avatarGlbUrl` (or `wolin:avatarVrmUrl`) and `wolin:displayName`, and spawn their 3D avatar with a zero-crash procedural fallback when unset. ```tsx import { Suspense, useEffect, useState } from 'react'; import { useGLTF, Html } from '@react-three/drei'; import { fetchWebIdProfile, parseTurtle } from '@wolin-id/client'; import { useWolinSession } from '@wolin-id/react'; const WOLIN = 'https://wolin.id/ns#'; export function PlayerAvatar({ position = [0, 0, 0] as [number, number, number] }) { const { session } = useWolinSession(); const [avatarUrl, setAvatarUrl] = useState(null); const [name, setName] = useState('Guest'); useEffect(() => { if (!session?.webId) return; fetch(session.webId, { headers: { Accept: 'text/turtle' } }) .then((r) => r.text()) .then((ttl) => { const triples = parseTurtle(ttl, session.webId); const glb = triples.find((t) => t.predicate === `${WOLIN}avatarGlbUrl`)?.object; const label = triples.find((t) => t.predicate === `${WOLIN}displayName`)?.object; if (glb) setAvatarUrl(glb); if (label) setName(label); }); }, [session?.webId]); return ( {name} }> {avatarUrl ? : } ); } function GlbModel({ url }: { url: string }) { const { scene } = useGLTF(url); return ; } function FallbackCapsule() { return ( ); } ``` ### Block 2: `$0` YouTube / CHZZK `CSS3DRenderer` Live Stage + P2P Spatial Voice - **Broadcast Video (`$0` Egress)**: Never transcode or relay 1080p broadcast video through your own server when embedding public livestreams. Mount a YouTube Live (`https://www.youtube.com/embed/?autoplay=1&mute=0`) or CHZZK (`https://chzzk.naver.com/live/`) `