Improved cloudflare storage types

AGENTS.md

@@ -0,0 +1,38 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Root uses Bun workspaces; core package lives in `packages/openauth`.
+- Library source: `packages/openauth/src` (issuer, client, providers, storage, ui). Build output lands in `packages/openauth/dist`.
+- Tests: `packages/openauth/test` with `.test.ts` files aligned to source areas.
+- Examples: `examples/issuer/*` and `examples/client/*` show deployable issuers/clients.
+- Site/docs: `www` (Astro), generally independent of the core package.
+- Utility scripts: `scripts/format` for repo-wide formatting.
+
+## Build, Test, and Development Commands
+- Install deps: `bun install` (root; respects workspaces).
+- Build library: `cd packages/openauth && bun run build` (runs `script/build.ts`).
+- Run tests: `cd packages/openauth && bun test` (uses Bun’s test runner; `bunfig.toml` points to `test`).
+- Format: `./scripts/format` (runs Prettier across the repo and will auto-commit/push; prefer `bun x prettier --write "**/*.{js,jsx,ts,tsx,json,md,yaml,yml}"` locally before invoking).
+
+## Coding Style & Naming Conventions
+- TypeScript + ESM everywhere; prefer named exports from modules.
+- Prettier governs formatting (default settings; 2-space indent). Keep imports sorted by logical grouping.
+- File names are kebab- or lowercase (e.g., `issuer.ts`, `storage/memory.ts`); match existing patterns when adding modules.
+- Avoid introducing new dependencies without discussion; keep public exports under `src/` mirrored in `exports` map.
+
+## Testing Guidelines
+- Add unit tests beside related domains in `packages/openauth/test` (`<name>.test.ts`).
+- Use Bun’s assertions; keep tests deterministic and avoid network calls.
+- When adding providers/storage/ui flows, cover happy path plus failure/edge cases (invalid tokens, missing params, PKCE checks, etc.).
+- Run `bun test` before pushing; include any new fixtures under `test` rather than `src`.
+
+## Commit & Pull Request Guidelines
+- Follow the existing conventional style: `type(scope): short summary` (e.g., `feat(provider): add POST callback...`). `auto: format code` is reserved for the formatter script.
+- Reference PR/issue numbers in the subject or body when relevant (e.g., `(#245)`).
+- PRs should include: what changed, why, how to verify (commands), and screenshots for UI-facing changes (`www` or `src/ui`).
+- Keep commits focused; avoid mixing refactors with feature/bug fixes unless necessary.
+
+## Security & Configuration Tips
+- Do not commit secrets or tokens; examples rely on provider credentials set via environment variables.
+- Validate new callbacks/handlers against OAuth/OIDC expectations and ensure JWT/PKCE flows remain compliant.
+- If adding storage backends, ensure data keys and hashing remain consistent with existing implementations.

examples/issuer/cloudflare-cli/.editorconfig

@@ -0,0 +1,12 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.yml]
+indent_style = space

examples/issuer/cloudflare-cli/.gitignore

@@ -0,0 +1,167 @@
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+\*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+\*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+\*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+\*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.cache
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+.cache/
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+.cache
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.\*
+
+# wrangler project
+
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example
+.wrangler/

examples/issuer/cloudflare-cli/.prettierrc

@@ -0,0 +1,6 @@
+{
+	"printWidth": 140,
+	"singleQuote": true,
+	"semi": true,
+	"useTabs": true
+}

examples/issuer/cloudflare-cli/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "cloudflare-api-cloudflare-cli",
+	"version": "0.0.0",
+	"private": true,
+	"scripts": {
+		"deploy": "wrangler deploy",
+		"dev": "wrangler dev",
+		"start": "wrangler dev",
+		"test": "vitest",
+		"cf-typegen": "wrangler types"
+	},
+	"devDependencies": {
+		"@cloudflare/vitest-pool-workers": "^0.8.19",
+		"typescript": "^5.5.2",
+		"vitest": "~3.2.0",
+		"wrangler": "4.54.0"
+	},
+	"dependencies": {
+		"@openauthjs/openauth": "workspace:*"
+	}
+}

examples/issuer/cloudflare-cli/src/index.ts

@@ -0,0 +1,39 @@
+import { issuer } from "@openauthjs/openauth"
+import { CloudflareStorage } from "@openauthjs/openauth/storage/cloudflare"
+import { subjects } from "../../../subjects.js"
+import { PasswordProvider } from "@openauthjs/openauth/provider/password"
+import { PasswordUI } from "@openauthjs/openauth/ui/password"
+
+async function getUser(email: string) {
+  // Get user from database
+  // Return user ID
+  return "123"
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return issuer({
+      storage: CloudflareStorage<KVNamespace>({
+        namespace: env.CloudflareAuthKV,
+      }),
+      subjects,
+      providers: {
+        password: PasswordProvider(
+          PasswordUI({
+            sendCode: async (email, code) => {
+              console.log(email, code)
+            },
+          }),
+        ),
+      },
+      success: async (ctx, value) => {
+        if (value.provider === "password") {
+          return ctx.subject("user", {
+            id: await getUser(value.email),
+          })
+        }
+        throw new Error("Invalid provider")
+      },
+    }).fetch(request, env, ctx)
+  },
+}

examples/issuer/cloudflare-cli/test/env.d.ts

@@ -0,0 +1,3 @@
+declare module 'cloudflare:test' {
+	interface ProvidedEnv extends Env {}
+}

examples/issuer/cloudflare-cli/test/index.spec.ts

@@ -0,0 +1,24 @@
+import { env, createExecutionContext, waitOnExecutionContext, SELF } from 'cloudflare:test';
+import { describe, it, expect } from 'vitest';
+import worker from '../src/index';
+
+// For now, you'll need to do something like this to get a correctly-typed
+// `Request` to pass to `worker.fetch()`.
+const IncomingRequest = Request<unknown, IncomingRequestCfProperties>;
+
+describe('Hello World worker', () => {
+	it('responds with Hello World! (unit style)', async () => {
+		const request = new IncomingRequest('http://example.com');
+		// Create an empty context to pass to `worker.fetch()`.
+		const ctx = createExecutionContext();
+		const response = await worker.fetch(request, env, ctx);
+		// Wait for all `Promise`s passed to `ctx.waitUntil()` to settle before running test assertions
+		await waitOnExecutionContext(ctx);
+		expect(await response.text()).toMatchInlineSnapshot(`"Hello World!"`);
+	});
+
+	it('responds with Hello World! (integration style)', async () => {
+		const response = await SELF.fetch('https://example.com');
+		expect(await response.text()).toMatchInlineSnapshot(`"Hello World!"`);
+	});
+});

examples/issuer/cloudflare-cli/test/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../tsconfig.json",
+	"compilerOptions": {
+		"types": ["@cloudflare/vitest-pool-workers"]
+	},
+	"include": ["./**/*.ts", "../worker-configuration.d.ts"],
+	"exclude": []
+}

examples/issuer/cloudflare-cli/tsconfig.json

@@ -0,0 +1,45 @@
+{
+	"compilerOptions": {
+		/* Visit https://aka.ms/tsconfig.json to read more about this file */
+
+		/* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+		"target": "es2024",
+		/* Specify a set of bundled library declaration files that describe the target runtime environment. */
+		"lib": ["es2024"],
+		/* Specify what JSX code is generated. */
+		"jsx": "react-jsx",
+
+		/* Specify what module code is generated. */
+		"module": "es2022",
+		/* Specify how TypeScript looks up a file from a given module specifier. */
+		"moduleResolution": "Bundler",
+		/* Enable importing .json files */
+		"resolveJsonModule": true,
+
+		/* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */
+		"allowJs": true,
+		/* Enable error reporting in type-checked JavaScript files. */
+		"checkJs": false,
+
+		/* Disable emitting files from a compilation. */
+		"noEmit": true,
+
+		/* Ensure that each file can be safely transpiled without relying on other imports. */
+		"isolatedModules": true,
+		/* Allow 'import x from y' when a module doesn't have a default export. */
+		"allowSyntheticDefaultImports": true,
+		/* Ensure that casing is correct in imports. */
+		"forceConsistentCasingInFileNames": true,
+
+		/* Enable all strict type-checking options. */
+		"strict": true,
+
+		/* Skip type checking all .d.ts files. */
+		"skipLibCheck": true,
+		"types": [
+			"./worker-configuration.d.ts"
+		]
+	},
+	"exclude": ["test"],
+	"include": ["worker-configuration.d.ts", "src/**/*.ts"]
+}

examples/issuer/cloudflare-cli/vitest.config.mts

@@ -0,0 +1,11 @@
+import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
+
+export default defineWorkersConfig({
+	test: {
+		poolOptions: {
+			workers: {
+				wrangler: { configPath: './wrangler.jsonc' },
+			},
+		},
+	},
+});