Merged in feature/permit-policy-cleanup (pull request #210)

cleanup permit policies and correct documentation

* docs

* policy cleanup

* refactor

* Merge remote-tracking branch 'origin/feature/permit-policy-cleanup' into feature/permit-policy-cleanup

* docs and edits

cmd/auth_related/cognito.auth.harness/build_linux.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build Linux binaries for the cognito auth harness main.go
+# Usage examples:
+#   ./build_linux.sh                    # builds linux/amd64 -> cognito.auth.harness_linux_amd64
+#   ./build_linux.sh --arch arm64       # builds linux/arm64 -> cognito.auth.harness_linux_arm64
+#   ./build_linux.sh --all              # builds both amd64 and arm64
+#   ./build_linux.sh ./my_out           # custom output for single-arch build
+#
+# Notes:
+# - For AWS Graviton instances use --arch arm64
+# - For AWS CloudShell or x86 EC2 use default (amd64)
+#
+# Env overrides:
+#   GOARCH: target architecture (amd64|arm64) when not using --all
+#   CGO_ENABLED: 0 by default for cross-compilation
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"
+cd "$SCRIPT_DIR"
+
+GOOS=linux
+DEFAULT_ARCH="${GOARCH:-amd64}"
+CGO_ENABLED="${CGO_ENABLED:-0}"
+
+OUT_OVERRIDE=""
+ARCH_ARG=""
+BUILD_BOTH=false
+
+print_help() {
+  sed -n '1,35p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --arch)
+      ARCH_ARG="$2"; shift 2 ;;
+    --all)
+      BUILD_BOTH=true; shift ;;
+    -h|--help)
+      print_help; exit 0 ;;
+    --)
+      shift; break ;;
+    -* )
+      echo "Unknown option: $1" >&2; exit 1 ;;
+    * )
+      # positional: output override for single-arch build
+      OUT_OVERRIDE="$1"; shift ;;
+  esac
+done
+
+build_one() {
+  local arch="$1"
+  local out_path="$2"
+  echo "Building Linux binary (GOARCH=${arch})"
+  echo "  GOOS=${GOOS} GOARCH=${arch} CGO_ENABLED=${CGO_ENABLED}"
+  echo "  Output: ${out_path}"
+  GOOS="$GOOS" GOARCH="$arch" CGO_ENABLED="$CGO_ENABLED" \
+    go build -o "$out_path" main.go
+  echo "✅ Built ${out_path}"
+}
+
+if $BUILD_BOTH; then
+  build_one amd64 "cognito.auth.harness_linux_amd64"
+  build_one arm64 "cognito.auth.harness_linux_arm64"
+  exit 0
+fi
+
+ARCH="${ARCH_ARG:-$DEFAULT_ARCH}"
+DEFAULT_OUT="cognito.auth.harness_linux_${ARCH}"
+OUT_PATH="${OUT_OVERRIDE:-$DEFAULT_OUT}"
+
+build_one "$ARCH" "$OUT_PATH"

cmd/auth_related/permit.setup/build.linux.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build Linux AMD64 binary for AWS CloudShell
+# Usage: ./build.linux.sh
+#
+# Output: dist/setup_permit
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"
+cd "$SCRIPT_DIR"
+
+mkdir -p dist
+
+echo "Building Linux AMD64 binary for AWS CloudShell..."
+echo "  GOOS=linux GOARCH=amd64 CGO_ENABLED=0"
+
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o dist/setup_permit .
+
+echo "Built: dist/setup_permit"

cmd/auth_related/permit.setup/cleanup_default_roles.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Delete the default Permit.io roles that conflict with our resource names.
+# Only run this on a brand new environment since it creates conflicting roles to start that need
+# to be deleted.
+
+export PERMIT_API_KEY="permit_key_omitted"
+
+PROJECT_ID="default"
+ENV_ID="production"
+
+echo "Deleting conflicting default roles from Production environment..."
+echo ""
+
+# Delete the 'admin' role
+echo "Deleting 'admin' role..."
+curl -X DELETE "https://api.permit.io/v2/schema/${PROJECT_ID}/${ENV_ID}/roles/admin" \
+  -H "Authorization: Bearer ${PERMIT_API_KEY}" \
+  -H "Content-Type: application/json"
+echo ""
+
+# Delete the 'editor' role (doesn't conflict but keeping consistency)
+echo "Deleting 'editor' role..."
+curl -X DELETE "https://api.permit.io/v2/schema/${PROJECT_ID}/${ENV_ID}/roles/editor" \
+  -H "Authorization: Bearer ${PERMIT_API_KEY}" \
+  -H "Content-Type: application/json"
+echo ""
+
+# Delete the 'viewer' role (doesn't conflict but keeping consistency)
+echo "Deleting 'viewer' role..."
+curl -X DELETE "https://api.permit.io/v2/schema/${PROJECT_ID}/${ENV_ID}/roles/viewer" \
+  -H "Authorization: Bearer ${PERMIT_API_KEY}" \
+  -H "Content-Type: application/json"
+echo ""
+
+echo "Done! You can now run the setup script."

cmd/auth_related/permit.setup/permit_policies.yaml

@@ -30,13 +30,6 @@ resources:
       - patch
       - delete
 
-  - name: query
-    description: Query definitions and execution
-    actions:
-      - get
-      - post
-      - patch
-
   - name: document
     description: Document upload and management
     actions:
@@ -51,7 +44,7 @@ resources:
       - post
 
   - name: documents
-    description: Document search and listing operations
+    description: Label operations on documents
     actions:
       - get
       - post
@@ -69,8 +62,8 @@ resources:
       - post
       - patch
 
-  - name: home
-    description: Home page access
+  - name: labels
+    description: Label-based document lookup
     actions:
       - get
 
@@ -95,10 +88,6 @@ roles:
         - post
         - patch
         - delete
-      query:
-        - get
-        - post
-        - patch
       document:
         - get
         - post
@@ -116,7 +105,7 @@ roles:
         - get
         - post
         - patch
-      home:
+      labels:
         - get
 
   - name: user_admin
@@ -137,8 +126,6 @@ roles:
       folders:
         - get
         - post
-      home:
-        - get
 
   - name: auditor
     description: Full read-only access across the entire system for auditing and compliance
@@ -150,8 +137,6 @@ roles:
         - get
       clients:
         - get
-      query:
-        - get
       document:
         - get
       export:
@@ -162,7 +147,7 @@ roles:
         - get
       folders:
         - get
-      home:
+      labels:
         - get
 
   - name: client_user
@@ -190,7 +175,7 @@ roles:
         - get
         - post
         - patch
-      home:
+      labels:
         - get
     notes: |
       This role requires tenant-level filtering by client_id.
@@ -253,19 +238,14 @@ policy_mappings:
     - path: /client/{id}/export
       methods:
         POST: client:post
+    - path: /client/{id}/folders
+      methods:
+        GET: client:get
 
-  query_endpoints:
-    - path: /query
+  clients_endpoints:
+    - path: /clients
       methods:
-        GET: query:get
-        POST: query:post
-    - path: /query/{id}
-      methods:
-        GET: query:get
-        PATCH: query:patch
-    - path: /query/{id}/test
-      methods:
-        POST: query:post
+        GET: clients:get
 
   document_endpoints:
     - path: /document/{id}
@@ -289,10 +269,64 @@ policy_mappings:
       methods:
         GET: field-extractions:get
 
+  labels_endpoints:
+    - path: /documents/{documentId}/labels
+      methods:
+        POST: documents:post
+        GET: documents:get
+    - path: /labels/{labelName}/documents
+      methods:
+        GET: labels:get
+
+  folders_endpoints:
+    - path: /folders
+      methods:
+        POST: folders:post
+    - path: /folders/{folderId}
+      methods:
+        PATCH: folders:patch
+    - path: /folders/{folderId}/documents
+      methods:
+        GET: folders:get
+    - path: /folders/{folderId}/metrics
+      methods:
+        GET: folders:get
+
+  eula_endpoints:
+    - path: /eula
+      public: true
+    - path: /eula/status
+      authenticated: true
+      no_permission_check: true
+    - path: /eula/agree
+      authenticated: true
+      no_permission_check: true
+    - path: /admin/eula
+      methods:
+        GET: admin:get
+        POST: admin:post
+    - path: /admin/eula/{version_id}
+      methods:
+        GET: admin:get
+        PATCH: admin:patch
+    - path: /admin/eula/{version_id}/activate
+      methods:
+        POST: admin:post
+    - path: /admin/eula/agreements
+      methods:
+        GET: admin:get
+    - path: /admin/eula/compliance
+      methods:
+        GET: admin:get
+
+  identity_endpoints:
+    - path: /identity
+      authenticated: true
+      no_permission_check: true
+
   auth_endpoints:
     - path: /home
-      methods:
-        GET: home:get
+      public: true
     - path: /login
       public: true
     - path: /login-callback
@@ -300,6 +334,17 @@ policy_mappings:
     - path: /logout
       authenticated: true
       no_permission_check: true
+    - path: /eula
+      public: true
+    - path: /eula/status
+      authenticated: true
+      no_permission_check: true
+    - path: /eula/agree
+      authenticated: true
+      no_permission_check: true
+    - path: /identity
+      authenticated: true
+      no_permission_check: true
     - path: /swagger/*
       public: true
     - path: /metrics
@@ -315,14 +360,16 @@ dynamic_mapping:
     examples:
       - url: /client/AAA
         resource: client
-      - url: /query/019580df-ef65-7676-8de9-94435a93337a
-        resource: query
       - url: /document/019580df-b3f8-7348-9ab1-1e55b3f18ed7
         resource: document
       - url: /admin/users
         resource: admin
       - url: /field-extractions
         resource: field-extractions
+      - url: /labels/contract/documents
+        resource: labels
+      - url: /folders/019580df-1234-5678-abcd-1e55b3f18ed7/documents
+        resource: folders
 
   action_extraction:
     logic: HTTP method converted to lowercase
@@ -340,7 +387,9 @@ dynamic_mapping:
 
   # Implementation notes
   notes:
-    - Admin endpoints restricted to super_admin and admin roles only
+    - Admin endpoints restricted to super_admin and user_admin roles only
     - Auditor has read-only access across all resources
     - Client_user currently has access to all clients (no tenant isolation)
     - Tenant isolation will require application changes (not initial requirement)
+    - /identity, /eula/status, and /eula/agree are auth-only (bypass Permit.io authorization)
+    - /home and /eula are fully public paths (no auth or permit check)

cmd/auth_related/permit.setup/run.tool.sh

@@ -0,0 +1,11 @@
+# dev environment key
+# export PERMIT_API_KEY="permit_key_nwcB5ebXeeZyyt684otN2h70P7EVYWvFjp88QLObZK0uBFLArgPTidmkMxXGGoMh0aSbLTZ8lp9Qg72bYFde1B"
+# production key
+# export PERMIT_API_KEY="permit_key_UiT5HGXS2kwsWJbZOnzEI86Y2ut4tGqHQcTJoMP6XaqlKmlLFWMVLPwlx0faz35ABigea2htQ6RpGjRDLkLIkT"
+go run setup_permit.go -list
+# for dev setup (this works)
+#go run setup_permit.go -config permit_policies.yaml -project default -env dev
+
+# for production (this does not work)
+go run setup_permit.go -config permit_policies.yaml -project default -env production
+

cmd/auth_related/readme.md

@@ -2,7 +2,7 @@
 All cognito related research code here. Not suitable for production. Only for confirming things 
 work before placing them in the library. 
 
-##  cognito_test
+##  auth_related
 This is the harness to demonstrate running all of the cognito auth and RBAC in a simple standalone
 main.go.  This is standalong documentation for the library contained in `internal/cognitoauth`.