Skip to main content
The starter is a standalone Cloudflare Workers package with a small browser page and durable D1 session storage. Its server calls SharedGraph over public HTTP transport, without a privileged service binding. The browser receives an opaque cookie, never delegated tokens. Only a server-backed confidential client is supported.

​
Before you start

Install Node.js 24.13.1 or newer, npm, Git and a browser. Request registration with the default scopes and callback https://localhost:4303/callback. Have the issued client identifier and secret, and the operator’s exact network origin ready. For the hosted pilot, the network origin is https://api.sharedgraph.com. The standalone repository is a publication of the maintained starter source. Its public repository has not yet been published. Until publication, obtain a clean standalone checkout/export and its clone URL from the maintainer. The commands below accept that repository URL; they do not claim a public clone or hosted deployment has been verified.

​
Clone and configure

Replace <starter-repository-url> with the supplied repository URL, then run:
Add a top-level non-secret vars object in wrangler.jsonc, using your registered identifier and exact origins:
APP_ID and CLIENT_ID must match. Keep both origins exact, without a trailing slash or path. The configuration declares CLIENT_SECRET and BFF_ENCRYPTION_KEY as required secrets. Wrangler loads these from the process environment for local development; their values do not belong in vars. Do not create .dev.vars or .env for this walkthrough: a .dev.vars file takes precedence over process secrets. Keep credentials, local database state and tokens out of version control, screenshots and logs. Replacing the encryption key invalidates existing sealed sessions. For a deliberately registered synthetic local network only, use the operator-provided HTTP loopback network origin, set APP_ORIGIN to http://127.0.0.1:4303 in vars, add "LOCAL_ONLY": "true" there, and change dev.local_protocol in wrangler.jsonc to "http". Register http://127.0.0.1:4303/callback. Both origins must then be HTTP loopback. Do not apply this exception to the hosted pilot.

​
Run and post

From cloudflare, open Bash for the masked prompt below. Disable shell tracing, enter the issued client secret when prompted, and generate the sealing key directly into the environment. The secret value is not part of the command or shell history. Then run the single local startup command:
Keep that shell open while developing. After stopping the server with Ctrl-C, run unset CLIENT_SECRET BFF_ENCRYPTION_KEY and exit to clear the environment and leave Bash. A fresh generated key retires previous local sealed sessions. This initializes local D1 tables and starts Wrangler. It does not create a remote database. Open the exact configured application origin. The default is https://localhost:4303; accept or trust Wrangler’s development certificate in your browser before proceeding.
  1. Select Sign in with SharedGraph. The server creates a single-use login transaction with state, nonce and S256 PKCE, then redirects to the network provider.
  2. Complete network login if required and deliberately consent to the requested scopes. The callback binds the canonical actor through /api/session.
  3. The page displays your actor and Session current. If needed, select Check session to revalidate.
  4. Enter a short public contribution and select Publish post. A successful response displays a post receipt and Post published. The post identifier populates the read field.
  5. Select Read post to retrieve that canonical post through the authenticated proxy. Confirm the text you submitted. Select Sign out when finished.
Do not proceed with a protected view when session validation is unavailable. A 401 requires sign-in; 409 requires session revalidation; 429 or 503 advises retrying later using Check session. Other refusals are surfaced. The minimal page clears protected state and drafts when validation fails or it is hidden, revalidates on return, and never automatically retries a write. A richer UI can retain the original intent separately and offer an explicit same-intent retry after an uncertain response.

​
Understand the server boundary

/login initiates authorization, /callback consumes the login transaction, /session returns actor/scopes/CSRF/generation, /network/* proxies allowlisted authenticated API calls, and /logout retires the durable application session. Logout does not itself revoke the network grant. The starter checks canonical authority before operations and before publishing results, uses a durable refresh lease and strict token rotation, and compares read incarnation/witness signals. Application sessions admit requests for one hour. Concurrent refresh may advise retry later; uncertain refresh retires the session. See authorization, lifecycle and safety and errors before extending it.

​
Deployment

The exported repository’s Cloudflare README contains the workers.dev deployment guide. Deployment requires your own Cloudflare database, secret installation, an exact registered HTTPS callback and remote schema initialization. Running locally is not evidence of a hosted deployment. The pilot’s public repository publication and hosted proof remain separate operator-approved steps.