@dupecom/botcha-cloudflare 0.18.0 → 0.20.0

package/README.md

@@ -11,9 +11,9 @@ Reverse CAPTCHA that verifies AI agents and blocks humans. Running at the edge.
 - **Agent Registry** - Persistent agent identities (POST /v1/agents/register)
 - **Email-tied apps** - Email verification, account recovery, secret rotation
 - **Dashboard** - Per-app metrics with agent-first auth (device code flow)
-- **JWT security** - 5-min access tokens, refresh tokens, audience claims, IP binding, revocation
+- **JWT security** - 1-hr access tokens, refresh tokens, audience claims, IP binding, revocation
 - **Multi-tenant** - Per-app isolation, scoped tokens, rate limiting
-- **Server-side SDKs** - @botcha/verify (TS) + botcha-verify (Python)
+- **Server-side SDKs** - @dupecom/botcha-verify (TS) + botcha-verify (Python)
 
 ## Features
 

package/dist/apps.d.ts

@@ -22,6 +22,7 @@ export type KVNamespace = {
  */
 export interface AppConfig {
     app_id: string;
+    name?: string;
     secret_hash: string;
     created_at: number;
     rate_limit: number;
@@ -35,6 +36,7 @@ export interface AppConfig {
  */
 export interface CreateAppResult {
     app_id: string;
+    name?: string;
     app_secret: string;
     email: string;
     email_verified: boolean;
@@ -45,6 +47,7 @@ export interface CreateAppResult {
  */
 export type PublicAppConfig = {
     app_id: string;
+    name?: string;
     created_at: number;
     rate_limit: number;
     email: string;
@@ -90,9 +93,10 @@ export declare function generateVerificationCode(): string;
  *
  * @param kv - KV namespace for storage
  * @param email - Required owner email address
- * @returns {app_id, app_secret, email, email_verified, verification_required}
+ * @param name - Optional human-readable label for the app
+ * @returns {app_id, name, app_secret, email, email_verified, verification_required}
  */
-export declare function createApp(kv: KVNamespace, email: string): Promise<CreateAppResult>;
+export declare function createApp(kv: KVNamespace, email: string, name?: string): Promise<CreateAppResult>;
 /**
  * Get the plaintext verification code for an app (internal use only — for sending via email).
  *

package/dist/apps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACtF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAIF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAIF;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAOtC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOhE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAMjD;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiCxF;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAqBlC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCjD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CAiB7D;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAkBxC;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAC1B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAsBjC;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAS3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CA6BlB"}
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"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"}

package/dist/apps.js

@@ -79,9 +79,10 @@ export function generateVerificationCode() {
  *
  * @param kv - KV namespace for storage
  * @param email - Required owner email address
- * @returns {app_id, app_secret, email, email_verified, verification_required}
+ * @param name - Optional human-readable label for the app
+ * @returns {app_id, name, app_secret, email, email_verified, verification_required}
  */
-export async function createApp(kv, email) {
+export async function createApp(kv, email, name) {
     const app_id = generateAppId();
     const app_secret = generateAppSecret();
     const secret_hash = await hashSecret(app_secret);
@@ -90,6 +91,7 @@ export async function createApp(kv, email) {
     const verificationCodeHash = await hashSecret(verificationCode);
     const config = {
         app_id,
+        ...(name && { name }),
         secret_hash,
         created_at: Date.now(),
         rate_limit: 100, // Default: 100 requests/hour
@@ -105,6 +107,7 @@ export async function createApp(kv, email) {
     ]);
     return {
         app_id,
+        ...(name && { name }),
         app_secret, // ONLY returned at creation time!
         email,
         email_verified: false,
@@ -242,6 +245,7 @@ export async function getApp(kv, app_id) {
         // Return config WITHOUT secret_hash (security)
         return {
             app_id: config.app_id,
+            ...(config.name && { name: config.name }),
             created_at: config.created_at,
             rate_limit: config.rate_limit,
             email: config.email,

package/dist/auth.d.ts

@@ -5,7 +5,7 @@
  * - JTI (JWT ID) for revocation
  * - Audience claims for API scoping
  * - Client IP binding for additional security
- * - Short-lived access tokens (5 min) with refresh tokens (1 hour)
+ * - Short-lived access tokens (1 hour) with refresh tokens (1 hour)
  * - Token revocation via KV storage
  */
 /**
@@ -61,15 +61,40 @@ export interface TokenGenerationOptions {
     clientIp?: string;
     app_id?: string;
 }
+/**
+ * ES256 private key in JWK format
+ * { kty: "EC", crv: "P-256", x: "...", y: "...", d: "..." }
+ */
+export interface ES256SigningKeyJWK {
+    kty: string;
+    crv: string;
+    x: string;
+    y: string;
+    d: string;
+    kid?: string;
+}
+/**
+ * Derive the public key JWK from an ES256 private key JWK.
+ * Strips the `d` (private) parameter and sets standard fields.
+ * Used by the JWKS endpoint to publish the signing key.
+ */
+export declare function getSigningPublicKeyJWK(privateKeyJwk: ES256SigningKeyJWK): Omit<ES256SigningKeyJWK, 'd'> & {
+    kid: string;
+    use: string;
+    alg: string;
+};
 /**
  * Generate JWT tokens (access + refresh) after successful challenge verification
  *
- * Access token: 5 minutes, used for API access
- * Refresh token: 1 hour, used to get new access tokens
+ * Access token: 1 hour, used for API access
+ * Refresh token: 1 hour, used to get new access tokens without re-solving challenges
+ *
+ * When signingKey (ES256 JWK) is provided, tokens are signed with ES256.
+ * Otherwise falls back to HS256 with the shared secret (backward compat).
  */
 export declare function generateToken(challengeId: string, solveTimeMs: number, secret: string, env?: {
     CHALLENGES: KVNamespace;
-}, options?: TokenGenerationOptions): Promise<TokenCreationResult>;
+}, options?: TokenGenerationOptions, signingKey?: ES256SigningKeyJWK): Promise<TokenCreationResult>;
 /**
  * Revoke a token by its JTI
  *
@@ -81,11 +106,20 @@ export declare function revokeToken(jti: string, env: {
 /**
  * Refresh an access token using a valid refresh token
  *
- * Verifies the refresh token, checks revocation, and issues a new access token
+ * Verifies the refresh token, checks revocation, and issues a new access token.
+ * Supports both ES256 (asymmetric) and HS256 (symmetric) refresh tokens.
  */
 export declare function refreshAccessToken(refreshToken: string, env: {
     CHALLENGES: KVNamespace;
-}, secret: string, options?: TokenGenerationOptions): Promise<{
+}, secret: string, options?: TokenGenerationOptions, signingKey?: ES256SigningKeyJWK, publicKey?: {
+    kty: string;
+    crv: string;
+    x: string;
+    y: string;
+    kid?: string;
+    use?: string;
+    alg?: string;
+}): Promise<{
     success: boolean;
     tokens?: Omit<TokenCreationResult, 'refresh_token' | 'refresh_expires_in'> & {
         access_token: string;
@@ -96,6 +130,9 @@ export declare function refreshAccessToken(refreshToken: string, env: {
 /**
  * Verify a JWT token with security checks
  *
+ * Supports both ES256 (asymmetric) and HS256 (symmetric) tokens.
+ * The algorithm is detected from the token's protected header.
+ *
  * Checks:
  * - Token signature and expiry
  * - Revocation status (via JTI)
@@ -107,6 +144,14 @@ export declare function verifyToken(token: string, secret: string, env?: {
 }, options?: {
     requiredAud?: string;
     clientIp?: string;
+}, publicKey?: {
+    kty: string;
+    crv: string;
+    x: string;
+    y: string;
+    kid?: string;
+    use?: string;
+    alg?: string;
 }): Promise<{
     valid: boolean;
     payload?: BotchaTokenPayload;

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAmF9B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,GAC/B,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,GAAG,oBAAoB,CAAC,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0G1K;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6E3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrE"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAAA;IAChB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,iBAAiB,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,gBAAgB,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,kBAAkB,GAChC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAQ3E;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE,sBAAsB,EAChC,UAAU,CAAC,EAAE,kBAAkB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAsG9B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,GAC/B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,sBAAsB,EAChC,UAAU,CAAC,EAAE,kBAAkB,EAC/B,SAAS,CAAC,EAAE;IACV,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,GACA,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,GAAG,oBAAoB,CAAC,GAAG;QAC3E,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;KACnB,CAAA;IACD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAC,CAqID;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;IAAE,UAAU,EAAE,WAAW,CAAA;CAAE,EACjC,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,EACD,SAAS,CAAC,EAAE;IACV,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,GACA,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyF3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKrE"}

package/dist/auth.js

@@ -5,23 +5,54 @@
  * - JTI (JWT ID) for revocation
  * - Audience claims for API scoping
  * - Client IP binding for additional security
- * - Short-lived access tokens (5 min) with refresh tokens (1 hour)
+ * - Short-lived access tokens (1 hour) with refresh tokens (1 hour)
  * - Token revocation via KV storage
  */
-import { SignJWT, jwtVerify } from 'jose';
+import { SignJWT, jwtVerify, importJWK, decodeProtectedHeader } from 'jose';
+/**
+ * Derive the public key JWK from an ES256 private key JWK.
+ * Strips the `d` (private) parameter and sets standard fields.
+ * Used by the JWKS endpoint to publish the signing key.
+ */
+export function getSigningPublicKeyJWK(privateKeyJwk) {
+    const { d: _d, ...publicKey } = privateKeyJwk;
+    return {
+        ...publicKey,
+        kid: privateKeyJwk.kid || 'botcha-signing-1',
+        use: 'sig',
+        alg: 'ES256',
+    };
+}
 /**
  * Generate JWT tokens (access + refresh) after successful challenge verification
  *
- * Access token: 5 minutes, used for API access
- * Refresh token: 1 hour, used to get new access tokens
+ * Access token: 1 hour, used for API access
+ * Refresh token: 1 hour, used to get new access tokens without re-solving challenges
+ *
+ * When signingKey (ES256 JWK) is provided, tokens are signed with ES256.
+ * Otherwise falls back to HS256 with the shared secret (backward compat).
  */
-export async function generateToken(challengeId, solveTimeMs, secret, env, options) {
-    const encoder = new TextEncoder();
-    const secretKey = encoder.encode(secret);
+export async function generateToken(challengeId, solveTimeMs, secret, env, options, signingKey) {
+    // Determine signing algorithm and key
+    let signKey;
+    let protectedHeader;
+    if (signingKey) {
+        // ES256 asymmetric signing
+        signKey = (await importJWK(signingKey, 'ES256'));
+        protectedHeader = {
+            alg: 'ES256',
+            kid: signingKey.kid || 'botcha-signing-1',
+        };
+    }
+    else {
+        // HS256 symmetric signing (legacy fallback)
+        signKey = new TextEncoder().encode(secret);
+        protectedHeader = { alg: 'HS256' };
+    }
     // Generate unique JTIs for both tokens
     const accessJti = crypto.randomUUID();
     const refreshJti = crypto.randomUUID();
-    // Access token: 5 minutes
+    // Access token: 1 hour
     const accessTokenPayload = {
         type: 'botcha-verified',
         solveTime: solveTimeMs,
@@ -38,11 +69,12 @@ export async function generateToken(challengeId, solveTimeMs, secret, env, optio
         accessTokenPayload.app_id = options.app_id;
     }
     const accessToken = await new SignJWT(accessTokenPayload)
-        .setProtectedHeader({ alg: 'HS256' })
+        .setProtectedHeader(protectedHeader)
         .setSubject(challengeId)
+        .setIssuer('botcha.ai')
         .setIssuedAt()
-        .setExpirationTime('5m') // 5 minutes
-        .sign(secretKey);
+        .setExpirationTime('1h') // 1 hour
+        .sign(signKey);
     // Refresh token: 1 hour
     const refreshTokenPayload = {
         type: 'botcha-refresh',
@@ -54,16 +86,20 @@ export async function generateToken(challengeId, solveTimeMs, secret, env, optio
         refreshTokenPayload.app_id = options.app_id;
     }
     const refreshToken = await new SignJWT(refreshTokenPayload)
-        .setProtectedHeader({ alg: 'HS256' })
+        .setProtectedHeader(protectedHeader)
         .setSubject(challengeId)
+        .setIssuer('botcha.ai')
         .setIssuedAt()
         .setExpirationTime('1h') // 1 hour
-        .sign(secretKey);
+        .sign(signKey);
     // Store refresh token JTI in KV if env provided (for revocation tracking)
     // Also store aud, client_ip, and app_id so they carry over on refresh
     if (env?.CHALLENGES) {
         try {
-            const refreshData = { sub: challengeId, iat: Date.now() };
+            const refreshData = {
+                sub: challengeId,
+                iat: Date.now(),
+            };
             if (options?.aud) {
                 refreshData.aud = options.aud;
             }
@@ -83,7 +119,7 @@ export async function generateToken(challengeId, solveTimeMs, secret, env, optio
     }
     return {
         access_token: accessToken,
-        expires_in: 300, // 5 minutes in seconds
+        expires_in: 3600, // 1 hour in seconds
         refresh_token: refreshToken,
         refresh_expires_in: 3600, // 1 hour in seconds
     };
@@ -105,15 +141,26 @@ export async function revokeToken(jti, env) {
 /**
  * Refresh an access token using a valid refresh token
  *
- * Verifies the refresh token, checks revocation, and issues a new access token
+ * Verifies the refresh token, checks revocation, and issues a new access token.
+ * Supports both ES256 (asymmetric) and HS256 (symmetric) refresh tokens.
  */
-export async function refreshAccessToken(refreshToken, env, secret, options) {
+export async function refreshAccessToken(refreshToken, env, secret, options, signingKey, publicKey) {
     try {
-        const encoder = new TextEncoder();
-        const secretKey = encoder.encode(secret);
+        // Detect algorithm from token header and verify accordingly
+        const header = decodeProtectedHeader(refreshToken);
+        let verifyKey;
+        let algorithms;
+        if (header.alg === 'ES256' && publicKey) {
+            verifyKey = (await importJWK(publicKey, 'ES256'));
+            algorithms = ['ES256'];
+        }
+        else {
+            verifyKey = new TextEncoder().encode(secret);
+            algorithms = ['HS256'];
+        }
         // Verify refresh token
-        const { payload } = await jwtVerify(refreshToken, secretKey, {
-            algorithms: ['HS256'],
+        const { payload } = await jwtVerify(refreshToken, verifyKey, {
+            algorithms,
         });
         // Check token type
         if (payload.type !== 'botcha-refresh') {
@@ -168,6 +215,20 @@ export async function refreshAccessToken(refreshToken, env, secret, options) {
                 console.error('Failed to verify refresh token in KV:', error);
             }
         }
+        // Determine signing algorithm and key for the new access token
+        let signKey;
+        let protectedHeaderObj;
+        if (signingKey) {
+            signKey = (await importJWK(signingKey, 'ES256'));
+            protectedHeaderObj = {
+                alg: 'ES256',
+                kid: signingKey.kid || 'botcha-signing-1',
+            };
+        }
+        else {
+            signKey = new TextEncoder().encode(secret);
+            protectedHeaderObj = { alg: 'HS256' };
+        }
         // Generate new access token
         const newAccessJti = crypto.randomUUID();
         const accessTokenPayload = {
@@ -189,16 +250,17 @@ export async function refreshAccessToken(refreshToken, env, secret, options) {
             accessTokenPayload.app_id = effectiveAppId;
         }
         const accessToken = await new SignJWT(accessTokenPayload)
-            .setProtectedHeader({ alg: 'HS256' })
+            .setProtectedHeader(protectedHeaderObj)
             .setSubject(payload.sub || '')
+            .setIssuer('botcha.ai')
             .setIssuedAt()
-            .setExpirationTime('5m') // 5 minutes
-            .sign(secretKey);
+            .setExpirationTime('1h') // 1 hour
+            .sign(signKey);
         return {
             success: true,
             tokens: {
                 access_token: accessToken,
-                expires_in: 300, // 5 minutes in seconds
+                expires_in: 3600, // 1 hour in seconds
             },
         };
     }
@@ -212,18 +274,33 @@ export async function refreshAccessToken(refreshToken, env, secret, options) {
 /**
  * Verify a JWT token with security checks
  *
+ * Supports both ES256 (asymmetric) and HS256 (symmetric) tokens.
+ * The algorithm is detected from the token's protected header.
+ *
  * Checks:
  * - Token signature and expiry
  * - Revocation status (via JTI)
  * - Audience claim (if provided)
  * - Client IP binding (if provided)
  */
-export async function verifyToken(token, secret, env, options) {
+export async function verifyToken(token, secret, env, options, publicKey) {
     try {
-        const encoder = new TextEncoder();
-        const secretKey = encoder.encode(secret);
-        const { payload } = await jwtVerify(token, secretKey, {
-            algorithms: ['HS256'],
+        // Detect algorithm from the token header
+        const header = decodeProtectedHeader(token);
+        let verifyKey;
+        let algorithms;
+        if (header.alg === 'ES256' && publicKey) {
+            // ES256 asymmetric verification
+            verifyKey = (await importJWK(publicKey, 'ES256'));
+            algorithms = ['ES256'];
+        }
+        else {
+            // HS256 symmetric verification (legacy/fallback)
+            verifyKey = new TextEncoder().encode(secret);
+            algorithms = ['HS256'];
+        }
+        const { payload } = await jwtVerify(token, verifyKey, {
+            algorithms,
         });
         // Check token type (must be access token, not refresh token)
         if (payload.type !== 'botcha-verified') {

package/dist/dashboard/docs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * BOTCHA API Documentation Page
+ *
+ * Public API docs at /docs — no authentication required.
+ * Renders all endpoints grouped by category with request/response
+ * examples, install instructions, and quick-start guides.
+ *
+ * Follows the ShowcasePage pattern: self-contained JSX with own
+ * HTML shell, inline CSS, and the shared DASHBOARD_CSS base.
+ */
+import type { FC } from 'hono/jsx';
+export declare const DocsPage: FC<{
+    version: string;
+}>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/dashboard/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/dashboard/docs.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAsbnC,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAqpB5C,CAAC"}