feat(core): add fine-grain authorization support

.docs-drift.yaml

@@ -0,0 +1,100 @@
+# docs-drift configuration for opentdf/platform.
+#
+# This file is consumed by the docs-drift skill
+# (https://github.com/virtru-corp/agent-skills/tree/main/skills/developers/docs-drift)
+# when a contributor runs `/docs-drift` after editing SDK code. The skill scans
+# for new/changed exported Go symbols and proto RPCs, drafts MDX stubs for
+# opentdf/docs, and prepares a PR.
+#
+# Most of the values below mirror the skill's built-in OpenTDF defaults — they're
+# committed as a documentation artifact so the contract is discoverable in this
+# repo. The `mappings:` section below them adds repo-specific routing the skill
+# wouldn't otherwise know about.
+
+docs:
+  repo: ../docs                # Sibling clone of opentdf/docs
+  root: docs/sdks              # Docs root within opentdf/docs
+
+version:
+  tag_prefix: "sdk/"           # SDK is independently versioned (sdk/v0.X.Y)
+
+scan:
+  go_paths:                    # Where the scanner looks for Go source
+    - sdk/                     #   the public SDK package
+    - protocol/go/internal/    #   source-file codegen helpers (PR #3232 pattern)
+  proto_paths:                 # Where the scanner looks for .proto files
+    - service/
+  exclude_paths:               # Substring match — these are generated or test-only
+    - sdk/sdkconnect/          #   auto-generated Connect-RPC wrappers
+    - sdk/gen/                 #   generated proto code (legacy path)
+    - sdk/internal/            #   Go internal package
+
+# Mappings route new symbols to the right MDX file when the name-only sniff
+# can't find an existing reference. Keys are glob patterns matched against
+# the fully-qualified symbol name; values are doc paths (relative to the
+# docs repo root) with an optional #section anchor for the heading to
+# append under.
+#
+# First-match-wins, ordered by insertion. Put the most specific patterns
+# first; the catch-all patterns last.
+mappings:
+
+  # ── EntityIdentifier constructor helpers (PR #3232 pattern) ──────────────
+  # Live in protocol/go/internal/authorization/v2/ and get codegen-copied
+  # into protocol/go/authorization/v2/*.gen.go. They're documented in
+  # authorization.mdx under the ## EntityIdentifier section.
+  "ForToken":              docs/sdks/authorization.mdx#entityidentifier
+  "ForClientID":           docs/sdks/authorization.mdx#entityidentifier
+  "ForEmail":              docs/sdks/authorization.mdx#entityidentifier
+  "ForUserName":           docs/sdks/authorization.mdx#entityidentifier
+  "ForRegisteredResource": docs/sdks/authorization.mdx#entityidentifier
+  "WithRequestToken":      docs/sdks/authorization.mdx#entityidentifier
+
+  # ── SDK discovery / attribute checks ─────────────────────────────────────
+  # Methods on the SDK struct that read platform state without writing.
+  # All land in discovery.mdx alongside ListAttributes / AttributeExists / etc.
+  "SDK.List*":             docs/sdks/discovery.mdx
+  "SDK.Attribute*":        docs/sdks/discovery.mdx
+  "SDK.Validate*":         docs/sdks/discovery.mdx
+  "SDK.GetEntityAttributes": docs/sdks/discovery.mdx
+
+  # ── TDF mechanics and re-wrap helpers ────────────────────────────────────
+  # Package-level functions for TDF inspection and option building.
+  # CreateTDF, LoadTDF, and IsValidTdf already live in tdf.mdx; new
+  # adjacent helpers (e.g., WithPolicyFrom from DSPX-2603) belong there too.
+  "IsTDF":                 docs/sdks/tdf.mdx
+  "IsValidTdf":            docs/sdks/tdf.mdx
+  "WithPolicyFrom":        docs/sdks/tdf.mdx
+  "BulkDecrypt":           docs/sdks/tdf.mdx
+
+  # ── Platform-client setup options ────────────────────────────────────────
+  # The "Initializing the SDK client" section of platform-client.mdx is
+  # where setup-time options like WithPlatformEndpoint live. Newly-added
+  # With*-style construction options default here unless overridden above.
+  "With*":                 docs/sdks/platform-client.mdx#initializing-the-sdk-client
+
+  # ── Policy enum aliases (PR #3408 pattern) ───────────────────────────────
+  # Constants like policy.OperatorIn / policy.BooleanAnd added in
+  # protocol/go/internal/policy/enums.go. Documented under the enum tables
+  # in policy.mdx.
+  "Operator*":             docs/sdks/policy.mdx
+  "Boolean*":              docs/sdks/policy.mdx
+  "Rule*":                 docs/sdks/policy.mdx
+  "State*":                docs/sdks/policy.mdx
+
+  # ── Proto service RPCs ───────────────────────────────────────────────────
+  # Per-service mapping. Each service's RPCs map to its dedicated MDX.
+  "AuthorizationService.*":             docs/sdks/authorization.mdx
+  "AttributesService.*":                docs/sdks/policy.mdx
+  "ActionsService.*":                   docs/sdks/policy.mdx
+  "NamespaceService.*":                 docs/sdks/policy.mdx
+  "SubjectMappingService.*":            docs/sdks/policy.mdx
+  "ResourceMappingService.*":           docs/sdks/policy.mdx
+  "RegisteredResourcesService.*":       docs/sdks/policy.mdx
+  "ObligationsService.*":               docs/sdks/obligations.mdx
+  "KeyAccessServerRegistryService.*":   docs/sdks/policy.mdx
+  "KeyManagementService.*":             docs/sdks/policy.mdx
+  "UnsafeService.*":                    docs/sdks/policy.mdx
+  "EntityResolutionService.*":          docs/sdks/authorization.mdx
+  "AccessService.*":                    docs/sdks/tdf.mdx
+  "WellKnownService.*":                 docs/sdks/platform-client.mdx

.github/dependabot.yml

@@ -7,16 +7,22 @@ version: 2
 updates:
   # Dependabot for CI
   - package-ecosystem: github-actions
-    directory: /
+    directories:
+      - "/"
+      - "/otdfctl/e2e"
     schedule:
       interval: monthly
     commit-message:
       prefix: "chore(ci)"
 
   # Dependabot for internal deps
   # Add explicit entry as any go.mods need internal dep checks
+
+  # examples + BDD tests grouped together
   - package-ecosystem: gomod
-    directory: "/examples"
+    directories:
+      - "/examples"
+      - "/tests-bdd"
     commit-message:
       prefix: "fix(deps)"
     groups:
@@ -25,6 +31,23 @@ updates:
           - "github.com/opentdf/*"
     schedule:
       interval: daily
+
+  # lib/* modules grouped together
+  - package-ecosystem: gomod
+    directories:
+      - "/lib/fixtures"
+      - "/lib/flattening"
+      - "/lib/identifier"
+      - "/lib/ocrypto"
+    commit-message:
+      prefix: "fix(deps)"
+    groups:
+      external:
+        exclude-patterns:
+          - "github.com/opentdf/*"
+    schedule:
+      interval: daily
+
   - package-ecosystem: gomod
     directory: "/sdk"
     commit-message:
@@ -35,6 +58,7 @@ updates:
           - "github.com/opentdf/*"
     schedule:
       interval: daily
+
   - package-ecosystem: gomod
     directory: "/service"
     commit-message:
@@ -45,3 +69,25 @@ updates:
           - "github.com/opentdf/*"
     schedule:
       interval: daily
+
+  - package-ecosystem: gomod
+    directory: "/otdfctl"
+    commit-message:
+      prefix: "fix(deps)"
+    groups:
+      external:
+        exclude-patterns:
+          - "github.com/opentdf/*"
+    schedule:
+      interval: daily
+
+  - package-ecosystem: gomod
+    directory: "/protocol/go"
+    commit-message:
+      prefix: "fix(deps)"
+    groups:
+      external:
+        exclude-patterns:
+          - "github.com/opentdf/*"
+    schedule:
+      interval: daily

.github/release-please/release-please-config.main.json

@@ -19,6 +19,15 @@
     "lib/identifier": {
       "component": "lib/identifier"
     },
+    "otdfctl": {
+      "component": "otdfctl",
+      "extra-files": [
+        {
+          "type": "generic",
+          "path": "pkg/config/config.go"
+        }
+      ]
+    },
     "protocol/go": {
       "component": "protocol/go"
     },
@@ -41,4 +50,4 @@
       ]
     }
   }
-}
+}

.github/release-please/release-please-config.otdfctl.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "go",
+  "versioning": "always-bump-patch",
+  "separate-pull-requests": true,
+  "include-component-in-tag": true,
+  "pull-request-title-pattern": "chore(release): release ${component} ${version}",
+  "tag-separator": "/",
+  "packages": {
+    "otdfctl": {
+      "component": "otdfctl",
+      "extra-files": [
+        {
+          "type": "generic",
+          "path": "pkg/config/config.go"
+        }
+      ]
+    }
+  }
+}

.github/release-please/release-please-manifest.json

@@ -1,9 +1,10 @@
 {
-  "lib/fixtures": "0.4.0",
-  "lib/ocrypto": "0.8.0",
+  "lib/fixtures": "0.5.0",
+  "lib/ocrypto": "0.12.0",
   "lib/flattening": "0.1.3",
-  "lib/identifier": "0.2.0",
-  "protocol/go": "0.14.0",
-  "sdk": "0.11.0",
-  "service": "0.11.0"
+  "lib/identifier": "0.4.0",
+  "otdfctl": "0.32.0",
+  "protocol/go": "0.32.0",
+  "sdk": "0.21.0",
+  "service": "0.16.0"
 }

.github/scripts/connectivity-test.sh

@@ -22,8 +22,8 @@ while true; do
         # Introduce random delay before each execution (between 1 and 4 seconds)
         sleep $((RANDOM % 4 + 1))
 
-        echo "Running randomly selected command './otdfctl policy $random_subcommand list...'"
-        result=$(./otdfctl policy $random_subcommand list --with-client-creds '{"clientId":"opentdf","clientSecret":"secret"}' --host http://localhost:8080 | grep -i "success")
+        echo "Running randomly selected command './bin/otdfctl policy $random_subcommand list...'"
+        result=$(./bin/otdfctl policy $random_subcommand list --with-client-creds '{"clientId":"opentdf","clientSecret":"secret"}' --host http://localhost:8080 | grep -i "success")
         echo $result
         if [ -z "$result" ]; then
         echo "Failure: 'success' not found in output; CLI failed."

.github/scripts/init-temp-keys.sh

@@ -50,6 +50,9 @@ openssl rsa -in "$opt_output/kas-private.pem" -pubout -out "$opt_output/kas-cert
 openssl ecparam -name prime256v1 >ecparams.tmp
 openssl req -x509 -nodes -newkey ec:ecparams.tmp -subj "/CN=kas" -keyout "$opt_output/kas-ec-private.pem" -out "$opt_output/kas-ec-cert.pem" -days 365
 
+# Generate hybrid post-quantum key pairs (X-Wing, P256+ML-KEM-768, P384+ML-KEM-1024)
+go run ./service/cmd/keygen -output "$opt_output"
+
 mkdir -p keys
 openssl req -x509 -nodes -newkey RSA:2048 -subj "/CN=ca" -keyout keys/keycloak-ca-private.pem -out keys/keycloak-ca.pem -days 365
 printf "subjectAltName=DNS:localhost,IP:127.0.0.1" >keys/sanX509.conf

.github/scripts/watch.sh

@@ -53,18 +53,54 @@ done
 file_to_watch="$1"
 shift
 
+file_signature() {
+    if [[ ! -e "$1" ]]; then
+        echo "missing"
+        return
+    fi
+
+    if stat -c '%i:%s:%Y' "$1" >/dev/null 2>&1; then
+        stat -c '%i:%s:%Y' "$1"
+        return
+    fi
+
+    stat -f '%i:%z:%m' "$1"
+}
+
 wait_for_change_to() {
-    if which inotifywait; then
-        echo "[INFO] inotifywaiting to [${file_to_watch}]"
-        inotifywait -e modify -e move -e create -e delete -e attrib -r "${file_to_watch}"
+    if command -v inotifywait >/dev/null 2>&1; then
+        local watch_dir
+        local watch_name
+        local changed_file
+
+        watch_dir=$(dirname "${file_to_watch}")
+        watch_name=$(basename "${file_to_watch}")
+
+        echo "[INFO] inotifywaiting to [${file_to_watch}] via [${watch_dir}]"
+        while true; do
+            changed_file=$(inotifywait -q \
+                -e close_write \
+                -e moved_to \
+                -e delete \
+                -e attrib \
+                --format '%f' \
+                "${watch_dir}")
+
+            if [[ "${changed_file}" == "${watch_name}" ]]; then
+                return
+            fi
+        done
     else
-        m=$(date -r "${file_to_watch}" +%s)
+        local m
+        local n
+
+        m=$(file_signature "${file_to_watch}")
         echo "[INFO] stat checking [${file_to_watch}] from [${m}]"
         while true; do
             sleep 1
-            n=$(date -r "${file_to_watch}" +%s)
-            echo "[INFO] stat checking [${file_to_watch}] from [${m} < ${n}]"
-            if [[ $m < $n ]]; then
+            n=$(file_signature "${file_to_watch}")
+            echo "[INFO] stat checking [${file_to_watch}] from [${m} != ${n}]"
+            if [[ "${m}" != "${n}" ]]; then
                 return
             fi
         done

.github/scripts/work-init.sh

@@ -36,10 +36,16 @@ if ! cd "$ROOT_DIR"; then
   exit 1
 fi
 
+# Preserve the toolchain directive from the original go.work so that CI steps
+# reading go-version-file: go.work (e.g. govulncheck) continue to use the
+# correct Go version after the workspace is regenerated.
+ORIG_TOOLCHAIN=$(awk '/^toolchain / {print $2; exit}' go.work 2>/dev/null)
+
 echo "[INFO] Rebuilding partial go.work for [${component}]"
 case $component in
 lib/ocrypto | lib/fixtures | lib/flattening | lib/identifier | protocol/go)
   echo "[INFO] skipping for leaf package"
+  exit 0
   ;;
 sdk)
   rm -f go.work go.work.sum &&
@@ -59,8 +65,25 @@ examples)
     go work init &&
     go work use ./examples
   ;;
+otdfctl)
+  rm -f go.work go.work.sum &&
+    go work init &&
+    go work use ./otdfctl &&
+    # service and examples are needed for release branch checks
+    go work use ./service &&
+    go work use ./examples
+  ;;
 *)
   echo "[ERROR] unknown component [${component}]"
   exit 1
   ;;
 esac
+
+# Restore the toolchain directive if it was present in the original go.work.
+if [[ -n "${ORIG_TOOLCHAIN:-}" ]]; then
+  if ! go work edit -toolchain="$ORIG_TOOLCHAIN"; then
+    echo "[ERROR] unable to restore original toolchain [${ORIG_TOOLCHAIN}] in go.work"
+    exit 1
+  fi
+  echo "[INFO] Restored toolchain ${ORIG_TOOLCHAIN} in go.work"
+fi

.github/workflows/action-lint.yaml

@@ -19,7 +19,7 @@ jobs:
       pull-requests: write
       checks: write
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
       - name: "Run reviewdog actionlint"
@@ -36,7 +36,7 @@ jobs:
       actions: read # only needed for private repos
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false