[WIP] AuthZen API Implementation

[aaguiarz]

Description

What problem is being solved?

How is it being solved?

What changes are made to solve it?

References

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced AuthZEN service API with evaluation, subject/resource/action search, and PDP configuration discovery endpoints.
  • Added pagination support for search results.
  • Added idempotency controls for write operations (on_duplicate and on_missing flags).

• Improvements

  • Enhanced request validation and error handling across APIs.
  • Improved API documentation with detailed examples and descriptions.

• Chores

  • Updated GitHub Actions workflows to latest versions.
  • Added security governance configuration.
  • Updated Go dependencies.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

This PR introduces an AuthZEN service with comprehensive authorization evaluation, search, and PDP discovery endpoints via new protocol buffers. Concurrently, it extends the OpenFGA service with idempotency controls, tightens request/response validation patterns, and updates CI/CD workflows, security configurations, and documentation accordingly.

Changes

Cohort / File(s)	Summary
Security & Governance .github/SECURITY-INSIGHTS.yml	Introduces Security Insights 2.0 configuration defining schema version, repository metadata, team details, licensing, documentation resources, security assessments, champions, and tooling (Dependabot, Snyk, Socket).
Build Configuration .github/dependabot.yaml	Corrects YAML indentation for gomod and github-actions groups to properly nest dependencies keys under group definitions.
CI/CD Workflows .github/workflows/push.yaml, .github/workflows/review.yaml	Updates action versions: actions/checkout to v5.0.0, bufbuild/buf-setup-action to v1.50.0, and swagger-editor-validate to v1.5.1; adds PagerDuty failure alerting in push workflow.
Documentation README.md	Expands content with About section, Usage/SDK details, Contributing/build instructions, and OpenAPI generation workflows with explicit code examples and Buf registry references.
AuthZEN Service Proto authzen/v1/authzen_service.proto	Adds new AuthZenService with six RPCs (Evaluation, Evaluations, SubjectSearch, ResourceSearch, ActionSearch, GetConfiguration) including HTTP mappings, OpenAPI extensions, domain models (Subject, Resource, Action, pagination, filters), and comprehensive validation rules.
OpenFGA Service Proto Updates openfga/v1/openfga_service.proto	Introduces idempotency fields (on_duplicate in WriteRequestWrites, on_missing in WriteRequestDeletes); hardens validation with ContinuationToken patterns, ReadRequestTupleKey user constraints, and adds ListStoresRequest name filtering.
OpenAPI Specification docs/openapiv2/apidocs.swagger.json	Extends schema with 19 new public definitions (Action, Subject, Resource, Evaluation/Search responses, BatchCheck types, Endpoints, PolicyDecisionPoint, pagination); updates error field naming to snake\_case; adds AuthZEN configuration endpoint and search/evaluation paths.
Go Module Files go.mod, proto/go.mod	Adds new module declaration go.buf.build/openfga/go/openfga/api in go.mod; bumps Go toolchain from 1.22.3 to 1.23.0 and updates indirect dependencies (golang.org/x/net, golang.org/x/sys, golang.org/x/text) in proto/go.mod.
Validation Generator proto/openfga/v1/openfga_service.pb.validate.go	Introduces centralized regex patterns for ContinuationToken validation across Read, ReadAuthorizationModels, ReadChanges, ListStores, and ReadResponse messages; adds User pattern enforcement for ReadRequestTupleKey; enforces required tuple\_key presence in BatchCheckItem.

Sequence Diagrams

sequenceDiagram
    participant Client
    participant AuthZenService
    participant Storage
    participant Config

    rect rgb(200, 220, 240)
    note over Client,Config: Evaluation Flow
    Client->>AuthZenService: Evaluation(subject, resource, action, context)
    AuthZenService->>Storage: Query authorization model & relationships
    Storage-->>AuthZenService: Model + relationships
    AuthZenService->>AuthZenService: Evaluate decision (context applied)
    AuthZenService-->>Client: EvaluationResponse(allowed, context)
    end

    rect rgb(220, 240, 200)
    note over Client,Config: Batch Evaluations Flow
    Client->>AuthZenService: Evaluations([items with semantics])
    loop For each item
        AuthZenService->>Storage: Query relationships
        Storage-->>AuthZenService: Data
        AuthZenService->>AuthZenService: Evaluate per semantic (EXECUTE_ALL/DENY_ON_FIRST_DENY/PERMIT_ON_FIRST_PERMIT)
    end
    AuthZenService-->>Client: EvaluationsResponse([results, next_token])
    end

    rect rgb(240, 220, 200)
    note over Client,Config: Search & Discovery Flow
    Client->>AuthZenService: SubjectSearch/ResourceSearch/ActionSearch
    AuthZenService->>Storage: Query subjects/resources/actions (paginated)
    Storage-->>AuthZenService: Filtered list with pagination token
    AuthZenService-->>Client: SearchResponse(items, next_token)
    
    Client->>AuthZenService: GetConfiguration()
    AuthZenService->>Config: Fetch PDP metadata & endpoints
    Config-->>AuthZenService: PolicyDecisionPoint info
    AuthZenService-->>Client: GetConfigurationResponse(endpoints, capabilities)
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• #229: Introduces identical SECURITY-INSIGHTS.yml configuration for security governance baseline alignment.
• #233: Implements the same idempotency control fields (on_duplicate/on_missing) in Write/Delete request envelopes alongside related validation enhancements.

Suggested reviewers

• adriantam
• rhamzeh

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The PR title '[WIP] AuthZen API Implementation' is vague and generic, using '[WIP]' marker and broad term 'Implementation' without conveying specific meaningful details about what is being implemented or changed.	Replace '[WIP]' with a more descriptive title that highlights the specific changes, such as 'Add AuthZen API service with evaluation and search endpoints' or 'Implement AuthZen 1.0 specification with configuration discovery'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dosubot]

Related Documentation

Checked 6 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[coderabbitai]

Actionable comments posted: 9

🤖 Fix all issues with AI agents

In @.github/SECURITY-INSIGHTS.yml:
- Line 70: The security-policy URL value under the security-policy key is
malformed; update the value to point to the correct GitHub blob path and
filename casing (SECURITY.md) — e.g., replace the current
https://github.com/openfga/api/security.md with the full blob URL including
/blob/<branch>/SECURITY.md (or point to the org-level policy at
https://github.com/openfga/.github/blob/main/SECURITY.md) so the link resolves
correctly.

In @authzen/v1/authzen_service.proto:
- Around line 582-589: The enum values in EvaluationsSemantic must be renamed to
follow protobuf conventions: change the zero value to
EVALUATIONS_SEMANTIC_UNSPECIFIED = 0 and prefix all other values with the enum
name (e.g., EVALUATIONS_SEMANTIC_EXECUTE_ALL,
EVALUATIONS_SEMANTIC_DENY_ON_FIRST_DENY,
EVALUATIONS_SEMANTIC_PERMIT_ON_FIRST_PERMIT) and update any references,
including the Evaluations RPC description, to use the new enum names.

In @docs/openapiv2/apidocs.swagger.json:
- Around line 749-752: The OpenAPI schema uses the full Resource definition for
ResourceSearch which requires both type and id, but search contexts should allow
id to be optional; add a new definition named ResourceFilter (mirroring
SubjectFilter) that requires only "type" and makes "id" optional (include
optional "properties" as in Resource), then update any references in
ResourceSearch (or the "resource" $ref) to point to
"#/definitions/ResourceFilter" instead of "#/definitions/Resource" so the search
schema correctly treats id as optional.
- Around line 35-64: The GetConfiguration endpoint description claims it "does
not require authentication" but its operation (operationId "GetConfiguration"
under path "/.well-known/authzen-configuration") includes 401 and 403 responses;
update the OpenAPI fragment to make them consistent by either removing the 401
and 403 response entries from the GetConfiguration operation if it is truly
public, or revise the description to explain the circumstances that would cause
401/403 and keep the responses; modify the responses object accordingly to
reflect the chosen behavior so the documentation is consistent.
- Around line 164-170: In the OpenAPI parameter object for the query parameter
with "name": "name" update the "description" string to add a missing space after
the period between sentences so it reads "...will be returned. Multiple
results..." (i.e., insert a single space after "returned."). Ensure the
corrected description keeps the rest of the text unchanged.
- Around line 556-562: The evaluations array schema is missing size constraints;
update the "evaluations" property (the array whose items reference
"EvaluationsItemRequest") to include "minItems": 1 and a sensible "maxItems"
(e.g., 1000) to match other batch endpoints and prevent unbounded requests; add
these two fields to the evaluations object in the OpenAPI JSON.
- Around line 2766-2782: EvaluationResponseContext currently defines fields
reasonAdmin and reasonUser in camelCase which conflicts with the API's
snake_case convention; update the definition to use snake_case (reason_admin and
reason_user) and adjust any references to these properties across the
codebase/consumers to match, ensuring the "$ref":
"#/definitions/ResponseContextError" remains unchanged and preserving the type
semantics of those properties.

In @openfga/v1/openfga_service.proto:
- Around line 1838-1843: The regex for the continuation_token field contains a
duplicate empty-string alternative; update the (validate.rules).string.pattern
for the field named continuation_token to remove the redundant `^$|` so it
matches the same pattern used elsewhere (`^$|^[A-Za-z0-9-_]+={0,2}$`); locate
the continuation_token declaration in openfga_service.proto and replace the
current pattern `^$|^$|^[A-Za-z0-9-_]+={0,2}$` with the single-empty alternative
version `^$|^[A-Za-z0-9-_]+={0,2}$`.

In @proto/openfga/v1/openfga_service.pb.validate.go:
- Around line 7056-7065: The regex for ListStoresRequest.continuation_token
includes a duplicated empty-alt prefix; update the proto pattern from
`^$|^$|^[A-Za-z0-9-_]+={0,2}$` to `^$|^[A-Za-z0-9-_]+={0,2}$` (remove the
redundant `^$|`), regenerate the Go validation code so
`_ListStoresRequest_ContinuationToken_Pattern` (and the analogous pattern used
at the other occurrence) is updated accordingly, and ensure the validation in
the generated method that checks m.GetContinuationToken() uses the corrected
pattern.

🧹 Nitpick comments (10)

.github/dependabot.yaml (1)

9-12: Consider more descriptive group names to clarify which ecosystem each group applies to.

The group name dependencies is generic and doesn't indicate it applies to either gomod or github-actions updates. Use ecosystem-aware names like gomod and github-actions (or alternatively gomod-updates and actions-updates) to improve clarity when reviewing grouped updates.

📝 Optional refactor for clearer group names

For the gomod ecosystem:

     groups:
-      dependencies:
+      gomod:
         patterns:
           - "*"

For the github-actions ecosystem:

     groups:
-      dependencies:
+      github-actions:
         patterns:
           - "*"

README.md (3)

6-6: Minor: Use hyphenated "open-source" as a compound adjective.

Per grammar conventions, "open-source" should be hyphenated when used as an adjective before a noun.

📝 Suggested fix

-[OpenFGA](https://openfga.dev) is an open source Fine-Grained Authorization solution inspired by [Google's Zanzibar paper](https://research.google/pubs/pub48190/).
+[OpenFGA](https://openfga.dev) is an open-source Fine-Grained Authorization solution inspired by [Google's Zanzibar paper](https://research.google/pubs/pub48190/).

---

15-15: Minor: Convert bare URL to markdown link.

Bare URLs can cause rendering issues in some markdown parsers. Consider wrapping in angle brackets or using link syntax.

📝 Suggested fix

-You can find various SDKs autogenerated by buf based on the protobuf definitions here: https://buf.build/openfga/api/sdks/main:protobuf 
+You can find various SDKs autogenerated by buf based on the protobuf definitions here: <https://buf.build/openfga/api/sdks/main:protobuf>

---

23-23: Minor: Convert bare URL to markdown link.

📝 Suggested fix

-If you are looking for the currently supported OpenFGA HTTP SDKs, you can find them here: https://github.com/openfga/sdk-generator#currently-supported-sdks
+If you are looking for the currently supported OpenFGA HTTP SDKs, you can find them here: <https://github.com/openfga/sdk-generator#currently-supported-sdks>

authzen/v1/authzen_service.proto (3)

514-517: Consider adding validation pattern to Resource.id.

The Resource.type field has a validation pattern (^[^:#@\\s]{1,50}$), but Resource.id only has REQUIRED behavior without pattern validation. This inconsistency may allow invalid resource IDs.

♻️ Suggested fix

   string id = 2 [
+    (validate.rules).string = {
+      pattern: "^[^:#@\\s]{1,500}$"
+      ignore_empty: false
+    },
     (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"roadmap\""}
   ];

---

641-641: Add validation pattern to authorization_model_id.

The authorization_model_id field in SubjectSearchRequest lacks the ULID validation pattern that's used consistently in openfga/v1/openfga_service.proto. The same issue exists in ResourceSearchRequest (line 676) and ActionSearchRequest (line 708).

♻️ Suggested fix for SubjectSearchRequest

-  string authorization_model_id = 7 [json_name = "authorization_model_id"];
+  string authorization_model_id = 7 [
+    json_name = "authorization_model_id",
+    (validate.rules).string = {
+      pattern: "^[ABCDEFGHJKMNPQRSTVWXYZ0-9]{26}$"
+      ignore_empty: true
+    },
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"01G5JAVJ41T49E9TT3SKVS7X1J\""}
+  ];

Apply the same pattern to lines 676 and 708.

---

597-602: Consider adding validation pattern to PageRequest.token.

The continuation token should follow the same Base64 URL-safe pattern used elsewhere in the codebase (^$|^[A-Za-z0-9-_]+={0,2}$) to ensure consistency.

♻️ Suggested fix

 message PageRequest {
   // Continuation token from previous response
-  optional string token = 1;
+  optional string token = 1 [
+    (validate.rules).string = {
+      pattern: "^$|^[A-Za-z0-9-_]+={0,2}$"
+      max_bytes: 5120
+    }
+  ];
   // Maximum number of results to return (default: 50, max: 1000)
   optional uint32 limit = 2 [(validate.rules).uint32 = {lte: 1000}];
 }

docs/openapiv2/apidocs.swagger.json (3)

17-24: Tag naming inconsistency with endpoint tags.

The tag defined here is AuthZenService, but the AuthZen endpoints (e.g., lines 90-92, 571-573) use AuthZen as the tag. Consider aligning these for consistency—either define both AuthZen and AuthZenService tags, or update the endpoint tags to match this definition.

---

442-467: Consider extracting inline schema to a named definition.

The request body schema is defined inline rather than using a $ref to a named definition. For maintainability and consistency with other endpoints (e.g., BatchCheck uses $ref to BatchCheckItem), consider extracting this to EvaluationRequest definition.

Additionally, unlike the Check endpoint, this lacks a consistency parameter. Verify if this omission is intentional for the AuthZen API.

---

3132-3136: Consider using int32 for pagination limit.

The limit field uses int64 format, but pagination limits elsewhere in this API use int32 (e.g., page_size at line 2001). With a maximum of 1000 results, int32 is sufficient and maintains consistency.

Suggested fix

         "limit": {
           "type": "integer",
-          "format": "int64",
+          "format": "int32",
           "title": "Maximum number of results to return (default: 50, max: 1000)"
         }

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between feed3db and 93293b6.

⛔ Files ignored due to path filters (5)

• proto/authzen/v1/authzen_service.pb.go is excluded by !**/*.pb.go
• proto/authzen/v1/authzen_service.pb.gw.go is excluded by !**/*.pb.gw.go
• proto/authzen/v1/authzen_service_grpc.pb.go is excluded by !**/*.pb.go
• proto/go.sum is excluded by !**/*.sum
• proto/openfga/v1/openfga_service.pb.go is excluded by !**/*.pb.go

📒 Files selected for processing (12)

• .github/SECURITY-INSIGHTS.yml
• .github/dependabot.yaml
• .github/workflows/push.yaml
• .github/workflows/review.yaml
• README.md
• authzen/v1/authzen_service.proto
• docs/openapiv2/apidocs.swagger.json
• go.mod
• openfga/v1/openfga_service.proto
• proto/authzen/v1/authzen_service.pb.validate.go
• proto/go.mod
• proto/openfga/v1/openfga_service.pb.validate.go

🧰 Additional context used

🪛 Checkov (3.2.334)

docs/openapiv2/apidocs.swagger.json

[medium] 556-561: Ensure that arrays have a maximum number of items

(CKV_OPENAPI_21)

🪛 GitHub Check: build

authzen/v1/authzen_service.proto

[failure] 588-588:
Enum value name "PERMIT_ON_FIRST_PERMIT" should be prefixed with "EVALUATIONS_SEMANTIC_".

---

[failure] 586-586:
Enum value name "DENY_ON_FIRST_DENY" should be prefixed with "EVALUATIONS_SEMANTIC_".

---

[failure] 584-584:
Enum zero value name "EXECUTE_ALL" should be suffixed with "_UNSPECIFIED".

---

[failure] 584-584:
Enum value name "EXECUTE_ALL" should be prefixed with "EVALUATIONS_SEMANTIC_".

🪛 LanguageTool

README.md

[grammar] ~6-~6: Use a hyphen to join words.
Context: ...OpenFGA](https://openfga.dev) is an open source Fine-Grained Authorization soluti...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.18.1)

README.md

15-15: Bare URL used

(MD034, no-bare-urls)

---

23-23: Bare URL used

(MD034, no-bare-urls)

🔇 Additional comments (28)

.github/dependabot.yaml (1)

1-1: LGTM! Schema directive enhances IDE support.

The YAML language server directive enables validation and autocomplete in compatible editors.

.github/workflows/push.yaml (2)

28-33: Good addition of failure alerting.

The PagerDuty alert step is well-configured: conditioned on failure(), uses secrets for the integration key, and provides a clear incident summary. Pinning to a commit hash is a good security practice.

---

20-24: No action needed—actions/checkout v5.0.0 is available.

The workflow correctly uses actions/checkout v5.0.0 (released August 11, 2025) and bufbuild/buf-setup-action v1.50.0, both pinned to commit hashes for good security practice.

Likely an incorrect or invalid review comment.

.github/workflows/review.yaml (3)

15-18: Consistent action version updates.

The actions/checkout and bufbuild/buf-setup-action updates are consistent with push.yaml. Both are pinned to commit hashes. The same verification concern about actions/checkout v5.0.0 applies here.

---

29-32: Consistent updates in diff-openapi job.

Same action version updates as the build job, maintaining consistency across the workflow.

---

44-46: Ownership change from char0n to swaggerexpert is confirmed as legitimate.

The swaggerexpert/swagger-editor-validate action is the official current maintainer listed in the GitHub Actions Marketplace, with v1.5.1 released recently (Feb 14, 2025). The change is safe to use.

.github/SECURITY-INSIGHTS.yml (2)

1-64: Well-structured Security Insights configuration.

The header, repository metadata, core team listing, and license information are comprehensive and follow the OSSF Security Insights 2.0 schema. Good practice to maintain this governance documentation.

---

72-113: Comprehensive security tooling and assessment documentation.

The security assessments section properly references the CNCF joint assessment, and the tools section documents a good mix of SCA (Dependabot, Snyk) and supply chain security (Socket) tooling with appropriate CI/release integration flags.

proto/go.mod (1)

3-16: LGTM! Dependency updates look reasonable.

The Go toolchain bump to 1.23.0 and the gRPC patch update to v1.64.1 are appropriate maintenance updates. The indirect dependency updates (especially golang.org/x/net to v0.38.0) often include important security patches.

openfga/v1/openfga_service.proto (5)

1256-1268: LGTM! Idempotency controls are well-designed.

The on_duplicate field with "error" (default) and "ignore" options provides clear control over write behavior. The OpenAPI documentation is comprehensive.

---

1278-1290: LGTM! Consistent idempotency design for deletes.

The on_missing field mirrors the on_duplicate pattern, providing symmetry in the API design for handling non-existent tuples during delete operations.

---

1419-1423: Verify impact of making tuple_key required in BatchCheckItem.

Adding (validate.rules).message.required = true to tuple_key is a breaking change for clients that may have been sending requests without this field. Ensure this is intentional and documented in migration guides.

---

1198-1204: Tighter validation for Read API user field.

The new pattern ^[^\\s]{1,511}:[^\\s]{1,511}$ enforces the type:id format with a colon separator, which is stricter than before. This is a good change for data consistency but may reject previously valid inputs.

Ensure existing clients are aware of this stricter validation requirement.

---

1844-1857: LGTM! Name filter for ListStores is a useful addition.

The optional name field with exact-match semantics provides filtering capability without introducing complex query patterns.

authzen/v1/authzen_service.proto (2)

415-450: LGTM! EvaluationRequest is well-structured.

The required fields (subject, resource, action) are properly validated, and the optional store_id and authorization_model_id have appropriate ULID patterns with ignore_empty: true.

---

376-412: LGTM! GetConfiguration follows AuthZEN spec section 13.

The well-known endpoint path /.well-known/authzen-configuration is correctly implemented for PDP discovery. The response structure with PolicyDecisionPoint, Endpoints, and capabilities aligns with the spec.

go.mod (1)

1-3: Go version 1.25.5 is valid. It is the latest stable release as of January 2026 and was recently published as a security update.

However, there is a version inconsistency: go.mod specifies Go 1.25.5 while proto/go.mod specifies Go 1.23.0. Consider aligning these versions, with preference for updating proto/go.mod to 1.25.5 to match the current stable release.

docs/openapiv2/apidocs.swagger.json (2)

3930-3966: LGTM! Well-designed idempotency options.

The on_duplicate and on_missing options are well-implemented with:

• Clear enum values (error, ignore)
• Sensible defaults (error preserves backward compatibility)
• Good documentation explaining the behavior

This provides explicit control over write/delete idempotency, which is valuable for operational safety.

---

2488-2501: This is not a breaking change to existing fields—CheckError is part of the new AuthZEN 1.0 API implementation.

The CheckError fields (input_error, internal_error) were defined with snake_case naming in the proto source file from the start, with explicit json_name directives. The swagger file is auto-generated from the proto definitions and reflects this intentional naming convention. Since this is a new API addition (not a modification to existing fields), there is no breaking change for existing clients.

Likely an incorrect or invalid review comment.

proto/openfga/v1/openfga_service.pb.validate.go (9)

1258-1267: LGTM: ContinuationToken validation for ReadRequest.

The pattern ^$|^[A-Za-z0-9-_]+={0,2}$ correctly enforces base64url-encoded tokens or empty strings, consistent with pagination token requirements.

Also applies to: 1359-1360

---

1383-1407: LGTM: User field validation for ReadRequestTupleKey.

The validation correctly:

• Guards pattern check on non-empty values
• Enforces max 512 bytes length
• Validates type:id format via pattern ^[^\s]{1,511}:[^\s]{1,511}$

Also applies to: 1519-1520

---

2962-2971: LGTM: TupleKey required validation for BatchCheckItem.

Adding the nil check ensures the required field is present before attempting embedded validation, consistent with other required field checks in this file (e.g., CheckRequest.TupleKey, ListUsersRequest.Object).

---

4746-4755: LGTM: ContinuationToken validation for ReadAuthorizationModels Request/Response.

Consistent pattern and structure with other ContinuationToken validations in the file.

Also applies to: 4840-4841, 4909-4918, 5001-5002

---

5629-5638: LGTM: ContinuationToken validation for ReadChanges Request/Response.

Consistent pattern and structure with other ContinuationToken validations in the file.

Also applies to: 5754-5755, 5823-5832, 5914-5915

---

7067-7080: LGTM: Name filter validation for ListStoresRequest.

The Name pattern ^[a-zA-Z0-9\s\.\-\/^_&@]{3,64}$ is consistent with CreateStoreRequest.Name validation, enabling users to filter stores by name with the same constraints.

Also applies to: 7164-7164

---

7233-7242: LGTM: ContinuationToken validation for ListStoresResponse.

Pattern is correct and consistent with other response message validations.

Also applies to: 7324-7325

---

1749-1750: LGTM: OnDuplicate and OnMissing fields without validation rules.

These idempotency control fields for Write API operations have no additional validation rules, which is acceptable as enum value validation is handled by protobuf deserialization. This aligns with the PR's objective to add idempotent options (on_duplicate, on_missing).

Also applies to: 1898-1899

---

1592-1601: LGTM: ContinuationToken validation for ReadResponse.

Pattern is correct and consistent with ReadRequest validation.

Also applies to: 1680-1681

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Security policy URL appears malformed.

The security-policy URL https://github.com/openfga/api/security.md is missing the blob path and uses incorrect casing. GitHub security policy files are typically at SECURITY.md (uppercase) and the full URL should include the blob path.

🔧 Suggested fix

-    security-policy: https://github.com/openfga/api/security.md
+    security-policy: https://github.com/openfga/api/blob/main/SECURITY.md

Alternatively, if using the organization-level security policy:

security-policy: https://github.com/openfga/.github/blob/main/SECURITY.md

🤖 Prompt for AI Agents

In @.github/SECURITY-INSIGHTS.yml at line 70, The security-policy URL value
under the security-policy key is malformed; update the value to point to the
correct GitHub blob path and filename casing (SECURITY.md) — e.g., replace the
current https://github.com/openfga/api/security.md with the full blob URL
including /blob/<branch>/SECURITY.md (or point to the org-level policy at
https://github.com/openfga/.github/blob/main/SECURITY.md) so the link resolves
correctly.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Fix enum naming to follow protobuf conventions (build failure).

The static analysis is failing because enum values don't follow the standard naming convention:

• Zero value should be suffixed with _UNSPECIFIED
• All values should be prefixed with the enum name

🐛 Proposed fix

 // Enum for evaluation semantics
 enum EvaluationsSemantic {
-  // Execute all evaluations (default behavior)
-  EXECUTE_ALL = 0;
-  // Stop on first deny decision
-  DENY_ON_FIRST_DENY = 1;
-  // Stop on first permit decision
-  PERMIT_ON_FIRST_PERMIT = 2;
+  // Unspecified - defaults to execute all
+  EVALUATIONS_SEMANTIC_UNSPECIFIED = 0;
+  // Execute all evaluations
+  EVALUATIONS_SEMANTIC_EXECUTE_ALL = 1;
+  // Stop on first deny decision
+  EVALUATIONS_SEMANTIC_DENY_ON_FIRST_DENY = 2;
+  // Stop on first permit decision
+  EVALUATIONS_SEMANTIC_PERMIT_ON_FIRST_PERMIT = 3;
 }

Note: This change also requires updating the documentation in the Evaluations RPC description (lines 159-162) to reference the new enum value names.

🧰 Tools

🪛 GitHub Check: build

[failure] 588-588:
Enum value name "PERMIT_ON_FIRST_PERMIT" should be prefixed with "EVALUATIONS_SEMANTIC_".

---

[failure] 586-586:
Enum value name "DENY_ON_FIRST_DENY" should be prefixed with "EVALUATIONS_SEMANTIC_".

---

[failure] 584-584:
Enum zero value name "EXECUTE_ALL" should be suffixed with "_UNSPECIFIED".

---

[failure] 584-584:
Enum value name "EXECUTE_ALL" should be prefixed with "EVALUATIONS_SEMANTIC_".

🤖 Prompt for AI Agents

In @authzen/v1/authzen_service.proto around lines 582 - 589, The enum values in
EvaluationsSemantic must be renamed to follow protobuf conventions: change the
zero value to EVALUATIONS_SEMANTIC_UNSPECIFIED = 0 and prefix all other values
with the enum name (e.g., EVALUATIONS_SEMANTIC_EXECUTE_ALL,
EVALUATIONS_SEMANTIC_DENY_ON_FIRST_DENY,
EVALUATIONS_SEMANTIC_PERMIT_ON_FIRST_PERMIT) and update any references,
including the Evaluations RPC description, to use the new enum names.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Documentation inconsistency regarding authentication.

The description states this endpoint "does not require authentication," but the response schema includes 401 (Not authenticated) and 403 (Forbidden) error responses. If this endpoint is truly public, consider removing these responses or clarifying when authentication might still apply.

🤖 Prompt for AI Agents

In @docs/openapiv2/apidocs.swagger.json around lines 35 - 64, The
GetConfiguration endpoint description claims it "does not require
authentication" but its operation (operationId "GetConfiguration" under path
"/.well-known/authzen-configuration") includes 401 and 403 responses; update the
OpenAPI fragment to make them consistent by either removing the 401 and 403
response entries from the GetConfiguration operation if it is truly public, or
revise the description to explain the circumstances that would cause 401/403 and
keep the responses; modify the responses object accordingly to reflect the
chosen behavior so the documentation is consistent.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Minor grammatical issue in description.

Missing space between sentences: "...will be returned.Multiple results..." should be "...will be returned. Multiple results...".

Suggested fix

-            "description": "The name parameter instructs the API to only include results that match that name.Multiple results may be returned. Only exact matches will be returned; substring matches and regexes will not be evaluated",
+            "description": "The name parameter instructs the API to only include results that match that name. Multiple results may be returned. Only exact matches will be returned; substring matches and regexes will not be evaluated",

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	{
	"name": "name",
	"description": "The name parameter instructs the API to only include results that match that name.Multiple results may be returned. Only exact matches will be returned; substring matches and regexes will not be evaluated",
	"in": "query",
	"required": false,
	"type": "string"
	}
	{
	"name": "name",
	"description": "The name parameter instructs the API to only include results that match that name. Multiple results may be returned. Only exact matches will be returned; substring matches and regexes will not be evaluated",
	"in": "query",
	"required": false,
	"type": "string"
	}

🤖 Prompt for AI Agents

In @docs/openapiv2/apidocs.swagger.json around lines 164 - 170, In the OpenAPI
parameter object for the query parameter with "name": "name" update the
"description" string to add a missing space after the period between sentences
so it reads "...will be returned. Multiple results..." (i.e., insert a single
space after "returned."). Ensure the corrected description keeps the rest of the
text unchanged.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Missing array size constraints on evaluations - potential resource exhaustion.

The evaluations array lacks maxItems and minItems constraints. Other batch operations in this API (e.g., BatchCheck at line 1369, WriteAssertions at line 1028) define these limits. Without constraints, clients could send unbounded arrays, potentially causing resource exhaustion.

Suggested fix

                 "evaluations": {
                   "type": "array",
                   "items": {
                     "type": "object",
                     "$ref": "#/definitions/EvaluationsItemRequest"
-                  }
+                  },
+                  "minItems": 1,
+                  "maxItems": 100
                 },

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	"evaluations": {
	"type": "array",
	"items": {
	"type": "object",
	"$ref": "#/definitions/EvaluationsItemRequest"
	}
	},
	"evaluations": {
	"type": "array",
	"items": {
	"type": "object",
	"$ref": "#/definitions/EvaluationsItemRequest"
	},
	"minItems": 1,
	"maxItems": 100
	},

🧰 Tools

🪛 Checkov (3.2.334)

[medium] 556-561: Ensure that arrays have a maximum number of items

(CKV_OPENAPI_21)

🤖 Prompt for AI Agents

In @docs/openapiv2/apidocs.swagger.json around lines 556 - 562, The evaluations
array schema is missing size constraints; update the "evaluations" property (the
array whose items reference "EvaluationsItemRequest") to include "minItems": 1
and a sensible "maxItems" (e.g., 1000) to match other batch endpoints and
prevent unbounded requests; add these two fields to the evaluations object in
the OpenAPI JSON.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Schema mismatch: Resource id required but optional in search context.

The Resource definition (lines 3372-3375) marks both type and id as required. However, for ResourceSearch, the resource serves as a type filter where id should be optional (similar to how SubjectFilter handles optional id for SubjectSearch).

Consider creating a ResourceFilter definition (analogous to SubjectFilter) for search operations where only type is required.

Suggested ResourceFilter definition

"ResourceFilter": {
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "example": "document"
    },
    "id": {
      "type": "string",
      "example": "roadmap",
      "title": "Optional resource id filter"
    },
    "properties": {
      "type": "object"
    }
  },
  "title": "ResourceFilter is used for search operations where id is optional",
  "required": [
    "type"
  ]
}

🤖 Prompt for AI Agents

In @docs/openapiv2/apidocs.swagger.json around lines 749 - 752, The OpenAPI
schema uses the full Resource definition for ResourceSearch which requires both
type and id, but search contexts should allow id to be optional; add a new
definition named ResourceFilter (mirroring SubjectFilter) that requires only
"type" and makes "id" optional (include optional "properties" as in Resource),
then update any references in ResourceSearch (or the "resource" $ref) to point
to "#/definitions/ResourceFilter" instead of "#/definitions/Resource" so the
search schema correctly treats id as optional.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

AuthZEN 1.0 specification response context field naming convention

💡 Result:

• The PDP response uses a top-level field named "context" (an object) to carry additional decision info. [1]

• AuthZEN 1.0 does not mandate a specific naming convention for keys inside that context object — the spec explicitly says the semantics/format of the context object are an implementation concern and gives only non‑normative examples (e.g., error, reason, advices/obligations). Implementations MAY reuse common keys from other standards (HTTP status, etc.) for interoperability. [1][2][3]

If you want, I can list the concrete example keys shown in the spec and drafts (error.status, error.message, reason, advice/obligations). [1][2][3]

Sources:
[1] AuthZEN Authorization API 1.0 (OpenID draft).
[2] draft-brossard OAuth RAR AuthZEN profile (IETF).
[3] AuthZEN subgroup / implementer notes (HackMD).

---

🏁 Script executed:

# Check the actual swagger file content around EvaluationResponseContext
cat -n docs/openapiv2/apidocs.swagger.json | sed -n '2760,2790p'

Repository: openfga/api

Length of output: 964

---

🏁 Script executed:

# Search for CheckError definition to verify snake_case naming claim
rg -n "CheckError" docs/openapiv2/apidocs.swagger.json -A 15 | head -40

Repository: openfga/api

Length of output: 588

---

🏁 Script executed:

# Search for other context definitions to understand the naming pattern
rg -n "Context.*:" docs/openapiv2/apidocs.swagger.json | grep "type.*object" -B 2 | head -30

Repository: openfga/api

Length of output: 4046

---

🏁 Script executed:

# Check for more context definitions and their naming patterns
rg -n "ResponseContext" docs/openapiv2/apidocs.swagger.json -A 10 | head -50

Repository: openfga/api

Length of output: 1063

---

🏁 Script executed:

# Look at other similar definition objects to establish naming patterns
rg -n '"[A-Z][a-zA-Z]*Context"' docs/openapiv2/apidocs.swagger.json | head -20

Repository: openfga/api

Length of output: 94

---

Address naming convention inconsistency in EvaluationResponseContext.

EvaluationResponseContext uses camelCase for reasonAdmin and reasonUser, while other error/response definitions in the API use snake_case (e.g., input_error, internal_error in CheckError). Align with the API's snake_case convention for consistency, or document the intentional deviation.

Note: The AuthZEN 1.0 specification does not mandate a specific naming convention for context object fields—this is treated as an implementation concern. The inconsistency is an internal API design issue rather than a spec compliance issue.

🤖 Prompt for AI Agents

In @docs/openapiv2/apidocs.swagger.json around lines 2766 - 2782,
EvaluationResponseContext currently defines fields reasonAdmin and reasonUser in
camelCase which conflicts with the API's snake_case convention; update the
definition to use snake_case (reason_admin and reason_user) and adjust any
references to these properties across the codebase/consumers to match, ensuring
the "$ref": "#/definitions/ResponseContextError" remains unchanged and
preserving the type semantics of those properties.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Bug: Duplicate ^$| prefix in continuation_token pattern.

The pattern ^$|^$|^[A-Za-z0-9-_]+={0,2}$ has a redundant ^$| prefix, unlike other continuation_token fields in this file which use ^$|^[A-Za-z0-9-_]+={0,2}$.

🐛 Proposed fix

   string continuation_token = 2 [
     json_name = "continuation_token",
     (validate.rules).string.max_bytes = 5120,
-    (validate.rules).string.pattern = "^$|^$|^[A-Za-z0-9-_]+={0,2}$",
+    (validate.rules).string.pattern = "^$|^[A-Za-z0-9-_]+={0,2}$",
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\""}
   ];

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	string continuation_token = 2 [
	json_name = "continuation_token",
	(validate.rules).string.max_bytes = 5120,
	(validate.rules).string.pattern = "^$|^$|^[A-Za-z0-9-_]+={0,2}$",
	(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\""}
	];
	string continuation_token = 2 [
	json_name = "continuation_token",
	(validate.rules).string.max_bytes = 5120,
	(validate.rules).string.pattern = "^$|^[A-Za-z0-9-_]+={0,2}$",
	(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\""}
	];

🤖 Prompt for AI Agents

In @openfga/v1/openfga_service.proto around lines 1838 - 1843, The regex for the
continuation_token field contains a duplicate empty-string alternative; update
the (validate.rules).string.pattern for the field named continuation_token to
remove the redundant `^$|` so it matches the same pattern used elsewhere
(`^$|^[A-Za-z0-9-_]+={0,2}$`); locate the continuation_token declaration in
openfga_service.proto and replace the current pattern
`^$|^$|^[A-Za-z0-9-_]+={0,2}$` with the single-empty alternative version
`^$|^[A-Za-z0-9-_]+={0,2}$`.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Get the specific lines mentioned in the review
echo "=== Lines 7056-7065 from openfga_service.pb.validate.go ==="
sed -n '7056,7065p' proto/openfga/v1/openfga_service.pb.validate.go

echo ""
echo "=== Lines 7162-7163 from openfga_service.pb.validate.go ==="
sed -n '7162,7164p' proto/openfga/v1/openfga_service.pb.validate.go

echo ""
echo "=== All ContinuationToken pattern definitions in the file ==="
rg -n 'ContinuationToken.*Pattern' proto/openfga/v1/openfga_service.pb.validate.go

echo ""
echo "=== All ContinuationToken regex patterns in the file ==="
rg -n '\^\\$\|.*A-Za-z0-9-_' proto/openfga/v1/openfga_service.pb.validate.go | head -20

Repository: openfga/api

Length of output: 2445

---

🏁 Script executed:

#!/bin/bash
# Find proto files
echo "=== Looking for proto files ==="
find . -name "*.proto" -type f | head -20

echo ""
echo "=== Searching for ListStoresRequest definition in proto files ==="
rg -n 'ListStoresRequest' --type=proto -A10 | grep -A10 'message ListStoresRequest'

echo ""
echo "=== Searching for continuation_token validation rule in proto files ==="
rg -n 'continuation_token.*=' --type=proto -B2 -A2

Repository: openfga/api

Length of output: 537

---

🏁 Script executed:

#!/bin/bash
# Search for ListStoresRequest in openfga_service.proto
echo "=== ListStoresRequest definition in openfga_service.proto ==="
rg -n 'ListStoresRequest' openfga/v1/openfga_service.proto -A15 | head -40

echo ""
echo "=== Searching for continuation_token validation rules ==="
rg -n 'continuation_token.*=' openfga/v1/openfga_service.proto -B2 -A2

Repository: openfga/api

Length of output: 3931

---

🏁 Script executed:

#!/bin/bash
# Search for all continuation_token patterns in the proto file to confirm the issue is only in ListStoresRequest
echo "=== All continuation_token pattern definitions in openfga_service.proto ==="
rg -n 'string.pattern.*\^' openfga/v1/openfga_service.proto | grep continuation_token

Repository: openfga/api

Length of output: 130

---

🏁 Script executed:

#!/bin/bash
# Get all continuation_token field definitions with their validation rules
echo "=== All continuation_token patterns in openfga_service.proto ==="
rg -n 'string continuation_token' openfga/v1/openfga_service.proto -A3

Repository: openfga/api

Length of output: 1737

---

Fix redundant ^$| in ListStoresRequest.continuation_token pattern.

The proto definition at line 1841 of openfga_service.proto specifies the pattern as ^$|^$|^[A-Za-z0-9-_]+={0,2}$, which has a redundant ^$| prefix. All other continuation_token fields in the proto use the correct pattern ^$|^[A-Za-z0-9-_]+={0,2}$ (with a single prefix). Update the proto definition to remove the duplicate.

Also applies to: 7162-7163

🤖 Prompt for AI Agents

In @proto/openfga/v1/openfga_service.pb.validate.go around lines 7056 - 7065,
The regex for ListStoresRequest.continuation_token includes a duplicated
empty-alt prefix; update the proto pattern from `^$|^$|^[A-Za-z0-9-_]+={0,2}$`
to `^$|^[A-Za-z0-9-_]+={0,2}$` (remove the redundant `^$|`), regenerate the Go
validation code so `_ListStoresRequest_ContinuationToken_Pattern` (and the
analogous pattern used at the other occurrence) is updated accordingly, and
ensure the validation in the generated method that checks
m.GetContinuationToken() uses the corrected pattern.