> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharedgraph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare starter

> Run a confidential application and create your first network post.

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](/registration) with the default [scopes](/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:

```bash theme={null}
git clone <starter-repository-url> sharedgraph-starter
cd sharedgraph-starter/cloudflare
npm ci
```

Add a top-level non-secret `vars` object in `wrangler.jsonc`, using your registered identifier and exact origins:

```json theme={null}
"vars": {
  "APP_ID": "your-registered-client-id",
  "CLIENT_ID": "your-registered-client-id",
  "APP_ORIGIN": "https://localhost:4303",
  "NETWORK_ORIGIN": "https://api.sharedgraph.com"
}
```

`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:

```bash theme={null}
bash
set +x
read -r -s -p 'Client secret: ' CLIENT_SECRET
printf '\n'
export CLIENT_SECRET
export BFF_ENCRYPTION_KEY="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('base64url'))")"
npm run dev
```

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](/authorization), [lifecycle and safety](/lifecycle-and-safety) and [errors](/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.