Context
We built a Harper app with Google OAuth, role-based access (admin/editor/viewer), session cookies, and a custom login page. The checking-authentication rule was our starting point, but we hit several behaviors that contradicted or weren't covered by the examples.
Caveat: These are patterns we arrived at through debugging. If Harper intends different approaches for any of these, the skill should document those — our workarounds may not be optimal.
1. 401 responses trigger browser Basic Auth dialogs
What we hit: We returned 401 Unauthorized from our custom resource (following the pattern in the auth rule's own examples). The browser popped a native username/password dialog instead of showing our custom login page.
Why we think it happens: Harper automatically adds a www-authenticate: Basic header to all 401 responses. This is standard HTTP behavior — browsers interpret 401 + www-authenticate as "show the credential prompt."
What we did: Switched every auth-failure response to 403 Forbidden. The auth rule's examples showing 401 actively led us down the wrong path.
What the skill should do: Either document this behavior and recommend 403 for browser-facing apps, or explain how to suppress the www-authenticate header if 401 is preferred. The current examples using 401 will cause this bug for anyone building a browser-based app with custom auth.
2. checkPermission = false for custom auth flows
What we hit: Even after implementing our own session-based auth, Harper's built-in permission system was rejecting requests before our code could run.
What we did: Set target.checkPermission = false early in our request handler to bypass Harper's built-in auth and let our custom auth logic handle it.
What the skill should do: Document when and how to use checkPermission = false. This is essential for any app implementing custom auth (OAuth, API keys, etc.) but isn't mentioned in the auth rule or anywhere in the skill.
3. No OAuth/OIDC patterns
What we hit: We needed Google OAuth for our app. The auth rule covers session-based login and JWT tokens, but has zero guidance on integrating with external identity providers.
What we did: Built a full Google OAuth flow from scratch: state parameter generation, token exchange, session cookie creation, redirect handling. It was ~300 lines of code that we had to figure out independently.
What the skill should do: At minimum, acknowledge that OAuth/OIDC is a common pattern and outline the approach (redirect → callback → session creation). A worked example for Google or GitHub OAuth would save significant time for anyone building a browser-facing Harper app.
4. Role-based access beyond super_user
What we hit: The auth rule's only role example is checking for super_user. Our app has admin/editor/viewer roles with different permissions.
What we did: Built our own role resolution system with a role mapping table and middleware that checks roles per-route.
What the skill should do: Show patterns for custom role hierarchies — even a simple example of "admin can write, viewer can only read" would help frame the approach.
Context
We built a Harper app with Google OAuth, role-based access (admin/editor/viewer), session cookies, and a custom login page. The
checking-authenticationrule was our starting point, but we hit several behaviors that contradicted or weren't covered by the examples.Caveat: These are patterns we arrived at through debugging. If Harper intends different approaches for any of these, the skill should document those — our workarounds may not be optimal.
1. 401 responses trigger browser Basic Auth dialogs
What we hit: We returned
401 Unauthorizedfrom our custom resource (following the pattern in the auth rule's own examples). The browser popped a native username/password dialog instead of showing our custom login page.Why we think it happens: Harper automatically adds a
www-authenticate: Basicheader to all 401 responses. This is standard HTTP behavior — browsers interpret 401 + www-authenticate as "show the credential prompt."What we did: Switched every auth-failure response to
403 Forbidden. The auth rule's examples showing401actively led us down the wrong path.What the skill should do: Either document this behavior and recommend 403 for browser-facing apps, or explain how to suppress the
www-authenticateheader if 401 is preferred. The current examples using 401 will cause this bug for anyone building a browser-based app with custom auth.2.
checkPermission = falsefor custom auth flowsWhat we hit: Even after implementing our own session-based auth, Harper's built-in permission system was rejecting requests before our code could run.
What we did: Set
target.checkPermission = falseearly in our request handler to bypass Harper's built-in auth and let our custom auth logic handle it.What the skill should do: Document when and how to use
checkPermission = false. This is essential for any app implementing custom auth (OAuth, API keys, etc.) but isn't mentioned in the auth rule or anywhere in the skill.3. No OAuth/OIDC patterns
What we hit: We needed Google OAuth for our app. The auth rule covers session-based login and JWT tokens, but has zero guidance on integrating with external identity providers.
What we did: Built a full Google OAuth flow from scratch: state parameter generation, token exchange, session cookie creation, redirect handling. It was ~300 lines of code that we had to figure out independently.
What the skill should do: At minimum, acknowledge that OAuth/OIDC is a common pattern and outline the approach (redirect → callback → session creation). A worked example for Google or GitHub OAuth would save significant time for anyone building a browser-facing Harper app.
4. Role-based access beyond
super_userWhat we hit: The auth rule's only role example is checking for
super_user. Our app has admin/editor/viewer roles with different permissions.What we did: Built our own role resolution system with a role mapping table and middleware that checks roles per-route.
What the skill should do: Show patterns for custom role hierarchies — even a simple example of "admin can write, viewer can only read" would help frame the approach.