feat: token scopes UI, scope tests, fh create completion, OpenAPI 1.0.0

Token scopes UI (Tokens.tsx)
- Scope selector in create-token dialog: read / write / deploy / admin
- Toggle buttons with primary highlight for selected scopes
- Scope description legend below the selector
- Defaults to [read, write, deploy] (backwards-compatible)
- Scopes sent in createMutation body, reset on dialog close
- Token list shows scope string when non-default
- Token interface now includes scopes field

Shell completion (completion.ts)
- fh create added to bash/zsh/fish command lists
- fh create --template flag with completions: html vite astro nextjs svelte
- fh create --no-install flag documented
- env command added to bash/fish command lists

Unit tests — tokenScopes.test.ts (21 assertions)
- Scope parsing: comma-separated, single, all, whitespace, empty string
- Backwards-compat default (read,write,deploy)
- Enforcement: read-only blocked from write, deploy-only blocked from write,
  write blocked from deploy, admin passes all, undefined scopes = session auth
- Validation: unknown scopes filtered, valid accepted, empty stays empty
- Serialisation round-trip: array → comma string → Set

OpenAPI 1.0.0
- Version bumped from 0.9.0 to 1.0.0
- New paths: webhooks CRUD, webhook deliveries, site clone,
  deployment diff, token list+create with scopes

Author: The No Hands Company

artifacts/api-server/tests/unit/tokenScopes.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from "vitest";
+
+// Mirror the scope logic from tokenAuth.ts
+type TokenScope = "read" | "write" | "deploy" | "admin";
+
+function parseScopes(raw: string): Set<TokenScope> {
+  return new Set<TokenScope>(
+    raw.split(",").map(s => s.trim()).filter(Boolean) as TokenScope[]
+  );
+}
+
+function hasScope(scopeSet: Set<TokenScope>, required: TokenScope): boolean {
+  return scopeSet.has(required);
+}
+
+// Mirror key validation from tokens.ts
+const VALID_SCOPES = ["read", "write", "deploy", "admin"] as const;
+function validateScopes(scopes: string[]): string[] {
+  return scopes.filter(s => (VALID_SCOPES as readonly string[]).includes(s));
+}
+
+describe("Token scope parsing", () => {
+  it("parses comma-separated scopes", () => {
+    const s = parseScopes("read,write,deploy");
+    expect(s.has("read")).toBe(true);
+    expect(s.has("write")).toBe(true);
+    expect(s.has("deploy")).toBe(true);
+    expect(s.has("admin")).toBe(false);
+  });
+
+  it("handles single scope", () => {
+    const s = parseScopes("read");
+    expect(s.has("read")).toBe(true);
+    expect(s.has("write")).toBe(false);
+  });
+
+  it("handles all scopes", () => {
+    const s = parseScopes("read,write,deploy,admin");
+    expect(s.size).toBe(4);
+    for (const scope of VALID_SCOPES) {
+      expect(s.has(scope)).toBe(true);
+    }
+  });
+
+  it("trims whitespace around scope names", () => {
+    const s = parseScopes("read, write , deploy");
+    expect(s.has("read")).toBe(true);
+    expect(s.has("write")).toBe(true);
+  });
+
+  it("empty string produces empty set", () => {
+    expect(parseScopes("").size).toBe(0);
+  });
+
+  it("default scope string matches backwards-compat default", () => {
+    const s = parseScopes("read,write,deploy");
+    // New tokens default to read+write+deploy
+    // Existing tokens that predate the scopes column also get this default
+    expect(s.has("read")).toBe(true);
+    expect(s.has("write")).toBe(true);
+    expect(s.has("deploy")).toBe(true);
+    expect(s.has("admin")).toBe(false);
+  });
+});
+
+describe("Scope enforcement (requireScope)", () => {
+  it("read-only token blocked from write route", () => {
+    const scopes = parseScopes("read");
+    expect(hasScope(scopes, "write")).toBe(false);
+  });
+
+  it("read-only token allowed on read route", () => {
+    const scopes = parseScopes("read");
+    expect(hasScope(scopes, "read")).toBe(true);
+  });
+
+  it("deploy-only token cannot write settings", () => {
+    const scopes = parseScopes("deploy");
+    expect(hasScope(scopes, "write")).toBe(false);
+    expect(hasScope(scopes, "deploy")).toBe(true);
+  });
+
+  it("write token cannot deploy", () => {
+    const scopes = parseScopes("read,write");
+    expect(hasScope(scopes, "deploy")).toBe(false);
+  });
+
+  it("admin token has all capabilities", () => {
+    const scopes = parseScopes("read,write,deploy,admin");
+    for (const scope of VALID_SCOPES) {
+      expect(hasScope(scopes, scope)).toBe(true);
+    }
+  });
+
+  it("session auth (no tokenScopes) always passes — no restriction", () => {
+    // When tokenScopes is undefined, requireScope passes through
+    const tokenScopes = undefined;
+    // Simulate the middleware: if (!req.tokenScopes) → next()
+    expect(tokenScopes).toBeUndefined();
+  });
+});
+
+describe("Scope validation on creation", () => {
+  it("filters out unknown scopes", () => {
+    const result = validateScopes(["read", "write", "superuser", "god"]);
+    expect(result).toEqual(["read", "write"]);
+  });
+
+  it("accepts all valid scopes", () => {
+    const result = validateScopes([...VALID_SCOPES]);
+    expect(result).toHaveLength(4);
+  });
+
+  it("empty array stays empty", () => {
+    expect(validateScopes([])).toHaveLength(0);
+  });
+
+  it("duplicates not deduplicated at validation layer (DB handles it)", () => {
+    const result = validateScopes(["read", "read", "write"]);
+    expect(result).toEqual(["read", "read", "write"]);
+  });
+});
+
+describe("Scope string serialisation (for DB storage)", () => {
+  it("array serialises to comma-separated string", () => {
+    const scopes = ["read", "write", "deploy"];
+    expect(scopes.join(",")).toBe("read,write,deploy");
+  });
+
+  it("round-trips: array → string → set", () => {
+    const original = ["read", "deploy"];
+    const stored   = original.join(",");
+    const parsed   = parseScopes(stored);
+    expect(parsed.has("read")).toBe(true);
+    expect(parsed.has("deploy")).toBe(true);
+    expect(parsed.has("write")).toBe(false);
+  });
+});

artifacts/cli/src/commands/completion.ts

@@ -28,6 +28,7 @@ _fh_completion() {
     -*)
       case "$prev" in
         deploy)   COMPREPLY=( $(compgen -W "--node --token" -- "$cur") ) ;;
+        create)   COMPREPLY=( $(compgen -W "--template --no-install" -- "$cur") ) ;;
         build)    COMPREPLY=( $(compgen -W "--git-url --branch --command --output --env --install --staging --wait" -- "$cur") ) ;;
         logs)     COMPREPLY=( $(compgen -W "--build --follow --limit" -- "$cur") ) ;;
         forms)    COMPREPLY=( $(compgen -W "--form --limit --export --json --unread" -- "$cur") ) ;;
@@ -57,6 +58,7 @@ _fh() {
   case $state in
     command)
       local commands=(
+        'create:Scaffold a new project from a template'
         'init:Initialise a new site in the current directory'
         'login:Authenticate with a FedHost node'
         'logout:Remove stored credentials'
@@ -115,6 +117,7 @@ const FISH_COMPLETION = `
 
 set -l commands init login logout whoami status deploy build logs sites forms tokens rollback analytics completion
 
+complete -c fh -f -n "not __fish_seen_subcommand_from $commands" -a create    -d "Scaffold new project from template"
 complete -c fh -f -n "not __fish_seen_subcommand_from $commands" -a init      -d "Initialise a new site"
 complete -c fh -f -n "not __fish_seen_subcommand_from $commands" -a login     -d "Authenticate with a node"
 complete -c fh -f -n "not __fish_seen_subcommand_from $commands" -a logout    -d "Remove stored credentials"
@@ -129,6 +132,10 @@ complete -c fh -f -n "not __fish_seen_subcommand_from $commands" -a tokens    -d
 complete -c fh -f -n "not __fish_seen_subcommand_from $commands" -a rollback  -d "Rollback deployment"
 complete -c fh -f -n "not __fish_seen_subcommand_from $commands" -a analytics -d "View analytics"
 
+# create flags
+complete -c fh -n "__fish_seen_subcommand_from create" -l template -a "html vite astro nextjs svelte" -d "Project template"
+complete -c fh -n "__fish_seen_subcommand_from create" -l no-install -d "Skip npm install"
+
 # build flags
 complete -c fh -n "__fish_seen_subcommand_from build" -l git-url  -d "Git repository URL"
 complete -c fh -n "__fish_seen_subcommand_from build" -l branch   -d "Branch to build"

artifacts/federated-hosting/src/pages/Tokens.tsx

@@ -22,6 +22,7 @@ interface ApiToken {
   tokenPrefix: string;
   lastUsedAt: string | null;
   expiresAt: string | null;
+  scopes:    string;
   createdAt: string;
 }
 
@@ -67,8 +68,9 @@ export default function TokensPage() {
   const qc = useQueryClient();
 
   const [createOpen, setCreateOpen] = useState(false);
-  const [newName, setNewName] = useState("");
-  const [newExpiry, setNewExpiry] = useState("");
+  const [newName, setNewName]       = useState("");
+  const [newExpiry, setNewExpiry]   = useState("");
+  const [newScopes, setNewScopes]   = useState<string[]>(["read", "write", "deploy"]);
   const [createdToken, setCreatedToken] = useState<CreatedToken | null>(null);
 
   const { data: tokens = [], isLoading } = useQuery<ApiToken[]>({
@@ -78,7 +80,7 @@ export default function TokensPage() {
   });
 
   const createMutation = useMutation({
-    mutationFn: (body: { name: string; expiresInDays?: number }) =>
+    mutationFn: (body: { name: string; expiresInDays?: number; scopes?: string[] }) =>
       apiFetch<CreatedToken>("/tokens", { method: "POST", body: JSON.stringify(body) }),
     onSuccess: (data) => {
       qc.invalidateQueries({ queryKey: ["tokens"] });
@@ -117,6 +119,7 @@ export default function TokensPage() {
     if (!newName.trim()) return;
     createMutation.mutate({
       name: newName.trim(),
+      scopes: newScopes,
       ...(newExpiry ? { expiresInDays: parseInt(newExpiry, 10) } : {}),
     });
   }
@@ -126,6 +129,7 @@ export default function TokensPage() {
     setCreatedToken(null);
     setNewName("");
     setNewExpiry("");
+    setNewScopes(["read", "write", "deploy"]);
   }
 
   return (
@@ -188,6 +192,29 @@ export default function TokensPage() {
                 </div>
                 <div>
                   <label className="text-sm text-muted-foreground mb-1.5 block">
+                    <div className="space-y-2">
+                      <label className="text-sm font-medium text-white">Permissions</label>
+                      <div className="flex flex-wrap gap-2">
+                        {(["read", "write", "deploy", "admin"] as const).map(scope => (
+                          <button key={scope} type="button"
+                            onClick={() => setNewScopes(s => s.includes(scope) ? s.filter(x => x !== scope) : [...s, scope])}
+                            className={`px-3 py-1.5 rounded-lg text-xs border transition-all ${
+                              newScopes.includes(scope)
+                                ? "bg-primary/10 border-primary/30 text-primary"
+                                : "border-white/10 text-muted-foreground hover:border-white/20"
+                            }`}>
+                            {scope}
+                          </button>
+                        ))}
+                      </div>
+                      <p className="text-xs text-muted-foreground">
+                        <span className="text-white">read</span> — view sites/analytics·
+                        <span className="text-white"> write</span> — edit settings·
+                        <span className="text-white"> deploy</span> — push files·
+                        <span className="text-white"> admin</span> — node admin
+                      </p>
+                    </div>
+
                     Expires in (days) <span className="text-muted-foreground/60">— leave blank for no expiry</span>
                   </label>
                   <input
@@ -274,6 +301,9 @@ export default function TokensPage() {
                         {token.lastUsedAt && (
                           <> · Last used {formatDistanceToNow(new Date(token.lastUsedAt), { addSuffix: true })}</>
                         )}
+                        {token.scopes && token.scopes !== "read,write,deploy" && (
+                          <span className="ml-1 text-xs text-primary/70">[{token.scopes}]</span>
+                        )}
                         {token.expiresAt && (
                           <> · Expires {formatDistanceToNow(new Date(token.expiresAt), { addSuffix: true })}</>
                         )}

lib/api-spec/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Federated Hosting API
-  version: 0.9.0
+  version: 1.0.0
   description: |
     Production-grade federated static site hosting network.
     Every node exposes this API. Authentication uses session cookies (browser)
@@ -2705,3 +2705,129 @@ components:
                   up:       {type: integer}
                   degraded: {type: integer}
                   down:     {type: integer}
+
+  /sites/{id}/webhooks:
+    get:
+      summary: List webhooks for a site
+      tags: [Webhooks]
+      security: [{sessionCookie: []}, {bearerToken: []}]
+      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
+      responses:
+        '200': {description: Webhook list (secrets masked)}
+    post:
+      summary: Create a webhook
+      tags: [Webhooks]
+      security: [{sessionCookie: []}, {bearerToken: []}]
+      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [url]
+              properties:
+                url:     {type: string, format: uri}
+                secret:  {type: string}
+                events:  {oneOf: [{type: string, enum: ['*']}, {type: array, items: {type: string}}]}
+                enabled: {type: boolean, default: true}
+      responses:
+        '201': {description: Webhook created}
+
+  /sites/{id}/webhooks/{hookId}:
+    patch:
+      summary: Update a webhook
+      tags: [Webhooks]
+      security: [{sessionCookie: []}, {bearerToken: []}]
+      parameters:
+        - {name: id,     in: path, required: true, schema: {type: integer}}
+        - {name: hookId, in: path, required: true, schema: {type: integer}}
+      responses:
+        '200': {description: Updated webhook}
+    delete:
+      summary: Delete a webhook
+      tags: [Webhooks]
+      security: [{sessionCookie: []}, {bearerToken: []}]
+      parameters:
+        - {name: id,     in: path, required: true, schema: {type: integer}}
+        - {name: hookId, in: path, required: true, schema: {type: integer}}
+      responses:
+        '204': {description: Deleted}
+
+  /sites/{id}/webhooks/{hookId}/deliveries:
+    get:
+      summary: List recent webhook delivery attempts
+      tags: [Webhooks]
+      security: [{sessionCookie: []}, {bearerToken: []}]
+      parameters:
+        - {name: id,     in: path, required: true, schema: {type: integer}}
+        - {name: hookId, in: path, required: true, schema: {type: integer}}
+      responses:
+        '200': {description: Last 50 deliveries with status, timing, retry count}
+
+  /sites/{id}/clone:
+    post:
+      summary: Clone a site — copy all files to a new domain
+      tags: [Sites]
+      security: [{sessionCookie: []}, {bearerToken: []}]
+      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name, domain]
+              properties:
+                name:   {type: string}
+                domain: {type: string}
+      responses:
+        '201': {description: Cloned site, no storage duplication (objectPaths reused)}
+
+  /sites/{id}/deployments/{depId}/diff:
+    get:
+      summary: File-level diff between two deployments
+      tags: [Sites]
+      security: [{sessionCookie: []}, {bearerToken: []}]
+      parameters:
+        - {name: id,    in: path,  required: true,  schema: {type: integer}}
+        - {name: depId, in: path,  required: true,  schema: {type: integer}}
+        - {name: base,  in: query, required: false, schema: {type: integer}, description: "Base deployment ID; defaults to previous version"}
+      responses:
+        '200':
+          description: Diff summary with added/changed/removed/unchanged file lists
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  summary: {type: object, properties: {added: {type: integer}, changed: {type: integer}, removed: {type: integer}, unchanged: {type: integer}, netSizeBytes: {type: integer}}}
+                  added:   {type: array}
+                  changed: {type: array}
+                  removed: {type: array}
+
+  /tokens:
+    get:
+      summary: List API tokens for the current user
+      tags: [Auth]
+      security: [{sessionCookie: []}]
+      responses:
+        '200': {description: Token list (hashes never returned, prefix shown)}
+    post:
+      summary: Create an API token
+      tags: [Auth]
+      security: [{sessionCookie: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name]
+              properties:
+                name:         {type: string}
+                scopes:       {type: array, items: {type: string, enum: [read, write, deploy, admin]}, default: [read, write, deploy]}
+                expiresInDays:{type: integer}
+      responses:
+        '201':
+          description: Token created — plaintext in `token` field, shown once only