Add the ability to request different scopes for different users/requests

.changeset/tiny-eels-deny.md

@@ -0,0 +1,5 @@
+---
+"@fujocoded/authproto": patch
+---
+
+Add the ability to request different scopes for different users/requests

astro-authproto/README.md

@@ -72,8 +72,7 @@ In this package, you'll find:
 - [Server adapter](https://docs.astro.build/en/guides/on-demand-rendering/#server-adapters) to set up sessions
 - (Optional) [session driver](https://docs.astro.build/en/reference/configuration-reference/#sessiondriver) to allow users to log in or log out
 
-> [!IMPORTANT]
-> `deno` requires a workaround due to a CJS/ESM import issue within
+> [!IMPORTANT] > `deno` requires a workaround due to a CJS/ESM import issue within
 > `@atproto/oauth-client-node`. For now, avoid using `deno` and use other package managers.
 
 > [!IMPORTANT]
@@ -92,7 +91,7 @@ npx astro add @fujocoded/authproto
 This will automatically install `@fujocoded/authproto` and add the integration to your `astro.config.mjs` file.
 
 > [!TIP]
-> 
+>
 > You can take a look at all the [possible configuration options below](#configuration-options).
 
 ### Manual Installation
@@ -138,8 +137,12 @@ import { Login } from "@fujocoded/authproto/components";
 <Login />
 ```
 
+You can also control what permissions your app asks for on different requests
+using the `scopes` and `additionalScopes` props! Check out the
+[custom scopes example](./__examples__/06-custom-scopes/) for all the details.
+
 > [!TIP]
-> 
+>
 > You might run into a naming collision issue if you also have a page named `login`. You can fix this by replacing `{ Login }` with `{ Login as LoginComponent }`.
 
 It'll look like a plain form:
@@ -199,6 +202,12 @@ Check out the example sites included under the [examples folder](./__examples__/
   - `additionalScopes`: array, optional. This is used in case you need to expand
     permissions to include other services. This should be an array of strings,
     like this: `["scope1", "scope2"]`
+- `defaultScopes`, optional. What your app asks for when no per-request scopes
+  are specified. Defaults to all configured `scopes`. Handy if you want to allow
+  a big set of scopes but only request a subset by default!
+- `resolveScopesEntrypoint`, optional. Path to a module that exports a
+  `resolveScopes(atprotoId, scopes)` function — use this if you need to tweak
+  scopes on the server side before the OAuth request goes out.
 
 # Support Us
 

astro-authproto/__examples__/06-custom-scopes/README.md

@@ -0,0 +1,57 @@
+# How to use custom scopes with `@fujocoded/authproto`
+
+By default, your app requests all the scopes you've configured. But sometimes
+you want to ask for different permissions depending on the situation!
+
+## Controlling scopes from the `<Login />` component
+
+Pass `scopes` to request exactly those (ignoring defaults — `atproto` is always
+included), or `additionalScopes` to tack extras onto your defaults:
+
+```jsx
+<!-- Just atproto, nothing else -->
+<Login scopes={[]} />
+
+<!-- Your default scopes + DMs -->
+<Login additionalScopes={["transition:chat.bsky"]} />
+```
+
+## Custom checkbox forms
+
+Want even more control? Build your own form with checkboxes that post directly
+to `/oauth/login`:
+
+```html
+<form action="/oauth/login" method="post">
+  <input name="atproto-id" placeholder="handle.bsky.social" />
+  <label><input type="checkbox" name="scope" value="transition:email" /> Email</label>
+  <label><input type="checkbox" name="scope" value="transition:generic" /> Read/write data</label>
+  <label><input type="checkbox" name="scope" value="transition:chat.bsky" /> DMs</label>
+  <button type="submit">Login</button>
+</form>
+```
+
+## Re-authenticating with different scopes
+
+Already logged in but want to change permissions? Post to `/oauth/login` again
+with the user's DID and new scope checkboxes — it'll start a fresh OAuth flow
+and update the session with the new scopes.
+
+## Checking granted scopes
+
+Once logged in, you can see what scopes a user has with
+`Astro.locals.loggedInUser.scopes`.
+
+## Configuration
+
+This example uses `defaultScopes` to request only a subset of the configured
+max scopes by default:
+
+```js
+authProto({
+  // Max allowed scopes
+  scopes: { email: true, genericData: true, directMessages: true },
+  // Only request these by default
+  defaultScopes: ["atproto", "transition:generic"],
+})
+```

astro-authproto/__examples__/06-custom-scopes/astro.config.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import authProto from "@fujocoded/authproto";
+
+// https://astro.build/config
+export default defineConfig({
+  output: "server",
+  session: {
+    driver: "memory",
+  },
+  integrations: [
+    authProto({
+      applicationName: "Custom Scopes Demo",
+      applicationDomain: "fujocoded.com",
+      defaultDevUser: "bobatan.fujocoded.com",
+      // We must specify all the scopes that this website may ever
+      // request, even if we'll override them in single requests.
+      scopes: {
+        email: true,
+        genericData: true,
+        directMessages: true,
+      },
+      // The default set of scopes this app will request
+      defaultScopes: {
+        genericData: true,
+      },
+    }),
+  ],
+});