Access Policy

Services

AccessPolicyService Service

Administers direct grants and code-defined role assignments.

Authentication: Every RPC requires gRPC metadata authorization: Bearer <api-key>.

Authorization Model:

• MANAGE_ACCESS is the operation used to inspect and modify a resource's policy.
• The service resolves the policy target before authorization, preserving GoodMem's distinct NOT_FOUND and PERMISSION_DENIED contract.
• Mutations re-evaluate target state and effective authority in their final SQL statement.
• Direct grants and scoped role assignments are permanent audit records. Revocation marks a row inactive rather than physically deleting it.

Global Errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, or INTERNAL in addition to their operation-specific errors.

CheckAuthorizations

Evaluates concrete authorization questions for the authenticated request principal.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Semantics: Every decision uses the caller's current live authority intersected with the immutable ceiling of the authenticating scoped API key. This RPC never evaluates a caller-supplied principal and does not reveal which role, grant, ownership rule, or ceiling produced a decision.

Target Semantics:

• Top-level create operations use INSTANCE; the check models a proposed resource owned by the caller. It is an authority preflight and does not validate a future resource ID, payload, or operation-specific precondition.
• CREATE_MEMORY and LIST_MEMORY use their parent SPACE.
• Collection and administrative operations whose authorization target is the singleton use INSTANCE. LIST_API_KEY and LIST_RETRIEVE_MEMORY_LOG_POLICY are not accepted because their current authorization algebra is candidate-resource based and has no honest instance-wide preflight answer.
• Reads, mutations, proxy operations, and access-policy administration use their concrete resource. Memory checks include the memory's direct-space containment facts.

Request Behavior: checks must contain between 1 and 50 items. Each operation must be recognized and paired with the target kind described above. Any malformed item rejects the complete request before evaluation.

Response: Returns exactly one positional decision per request item. A missing target and an authorization denial both produce allowed=false; the response deliberately does not distinguish those cases.

Side Effects: None. Decisions are advisory only. Every subsequent resource RPC performs its own validation and authorization against fresh state, so clients must tolerate a later denial.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Empty or oversized batch, unknown operation, malformed target, or incompatible operation/target pair.
• INTERNAL: Target resolution or authorization infrastructure failed.

Idempotency: Read-only and safe to retry. Concurrent policy or resource changes can alter a later response.

CreateAuthorizationGrant

Creates one direct authorization grant.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on the resolved policy target.

Request Behavior:

• audience must identify one active principal or ALL_AUTHENTICATED.
• rule must combine a compatible operation, selector, and assigned-resource shape.
• Direct grants cannot confer credential-read or ownership-transfer authority.
• ALL_AUTHENTICATED grants require EXACT or DIRECT_MEMBERS_OF.
• Principal-only administration operations (MANAGE_ACCESS and MANAGE_USER_ENROLLMENT) require a concrete principal audience and the ANY or EXACT selector.
• An EXACT MANAGE_USER_ENROLLMENT grant must target a USER resource.
• The server generates grant_id when the caller omits it.

Response: The newly created live AuthorizationGrant, including creation provenance.

Side Effects: Inserts one durable grant row. It does not change ownership, roles, API-key ceilings, or the audience principal.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed UUID, audience, rule, selector, or resource-kind combination; a principal-only administration rule with an invalid audience, selector, or target kind; or an operation that direct grants are forbidden to confer.
• NOT_FOUND: The policy target or principal audience does not exist in the required active state.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the policy target.
• ALREADY_EXISTS: The requested UUID or an equivalent live grant already exists.
• INTERNAL: Unexpected server or database failure.

Idempotency: Not inherently idempotent. Repeating a successful request returns ALREADY_EXISTS while the same live grant or caller-provided UUID remains occupied.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{
"audience": { "principal_id": "BASE64_ENCODED_PRINCIPAL_UUID" },
"rule": {
"operation": "ACCESS_POLICY_OPERATION_READ_SPACE",
"selector": "ACCESS_POLICY_SELECTOR_EXACT",
"assigned_resource": { "space_id": "BASE64_ENCODED_SPACE_UUID" }
}
}' \
localhost:8080 goodmem.v1.AccessPolicyService/CreateAuthorizationGrant

GetAuthorizationGrant

Retrieves one direct authorization grant by UUID.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on the grant's policy target.

Request Behavior:

• grant_id must contain one UUID.
• A live grant is eligible by default.
• include_revoked=true also permits the matching historical row to be returned.
• The target must still exist, and the caller must retain authority on that target.

Response: The matching live or historical AuthorizationGrant.

Side Effects: None; this is a read-only operation.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed grant UUID.
• NOT_FOUND: No eligible grant exists, or its policy target no longer exists.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the grant's policy target.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{ "grant_id": "BASE64_ENCODED_GRANT_UUID", "include_revoked": true }' \
localhost:8080 goodmem.v1.AccessPolicyService/GetAuthorizationGrant

ListAuthorizationGrants

Lists one stable page of grants attached to a policy target.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on assigned_resource.

Request Behavior:

• assigned_resource is required and identifies exactly one policy boundary.
• include_revoked=false lists live grants only; true includes historical rows.
• max_results defaults to 50 and may not exceed 1,000.
• next_token is opaque and bound to the requestor, target, and history flag.
• The target and caller authority are resolved again for every page.

Response: A ListAuthorizationGrantsResponse ordered by ascending creation time and grant UUID. next_token is absent after the final page.

Side Effects: None; this is a read-only operation.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed target, page size, or continuation token.
• NOT_FOUND: The requested policy target does not exist.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the policy target, or the pagination token belongs to a different authenticated requestor.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry. Concurrent policy changes may alter later pages.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{
"assigned_resource": { "space_id": "BASE64_ENCODED_SPACE_UUID" },
"include_revoked": false,
"max_results": 50
}' \
localhost:8080 goodmem.v1.AccessPolicyService/ListAuthorizationGrants

RevokeAuthorizationGrant

Permanently revokes one direct grant while preserving its audit history.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on the grant's policy target.

Request Behavior:

• grant_id must identify an existing current or historical grant.
• Revoking an already-revoked grant succeeds without changing its original revocation timestamp or actor.
• The target must still exist, and the caller must retain authority on that target.

Response: The historical AuthorizationGrant, including revocation time and actor.

Side Effects: On the first successful call, records revoked_at and the exact authenticated principal or API key as revoked_by_id. The grant row is never physically deleted.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed grant UUID.
• NOT_FOUND: The grant or its policy target does not exist.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the grant's policy target.
• INTERNAL: Unexpected server or database failure.

Idempotency: Authorized retries preserve and return the original revocation provenance.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{ "grant_id": "BASE64_ENCODED_GRANT_UUID" }' \
localhost:8080 goodmem.v1.AccessPolicyService/RevokeAuthorizationGrant

AssignRole

Assigns one code-defined role to an active principal at instance or space scope.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on assigned_resource.

Request Behavior:

• principal_id must identify an active HUMAN or SERVICE principal.
• role must be a concrete assignable role compatible with the requested scope.
• assigned_resource must identify the singleton instance or one memory space.
• ROOT cannot be assigned through this API because it mirrors instance ownership.
• The server generates role_assignment_id when the caller omits it.

Response: The newly created live RoleAssignment, including assignment provenance.

Side Effects: Inserts one durable role-assignment row. It does not transfer ownership, create credentials, or modify direct grants.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed UUID, unknown or prohibited role, missing target, or a role and target scope that are incompatible.
• NOT_FOUND: The receiving principal or assigned resource does not exist in the required active state.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the assigned resource.
• ALREADY_EXISTS: The requested UUID or equivalent live role assignment already exists.
• INTERNAL: Unexpected server or database failure.

Idempotency: Not inherently idempotent. Repeating a successful assignment returns ALREADY_EXISTS while the same live binding or caller-provided UUID remains occupied.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{
"principal_id": "BASE64_ENCODED_PRINCIPAL_UUID",
"role": "BUILT_IN_ROLE_SPACE_VIEWER",
"assigned_resource": { "space_id": "BASE64_ENCODED_SPACE_UUID" }
}' \
localhost:8080 goodmem.v1.AccessPolicyService/AssignRole

GetRoleAssignment

Retrieves one role assignment by UUID.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on the assignment's instance or space target.

Request Behavior:

• role_assignment_id must contain one UUID.
• A live assignment is eligible by default.
• include_revoked=true also permits the matching historical row to be returned.
• The target must still exist, and the caller must retain authority on that target.

Response: The matching live or historical RoleAssignment.

Side Effects: None; this is a read-only operation.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed role-assignment UUID.
• NOT_FOUND: No eligible assignment exists, or its assigned resource no longer exists.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the assigned resource.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{
"role_assignment_id": "BASE64_ENCODED_ROLE_ASSIGNMENT_UUID",
"include_revoked": true
}' \
localhost:8080 goodmem.v1.AccessPolicyService/GetRoleAssignment

ListRoleAssignments

Lists one stable page of role assignments attached to an instance or space.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on assigned_resource.

Request Behavior:

• assigned_resource must identify the singleton instance or one memory space.
• include_revoked=false lists live assignments only; true includes historical rows.
• max_results defaults to 50 and may not exceed 1,000.
• next_token is opaque and bound to the requestor, target, and history flag.
• The target and caller authority are resolved again for every page.

Response: A ListRoleAssignmentsResponse ordered by ascending assignment time and UUID. next_token is absent after the final page.

Side Effects: None; this is a read-only operation.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed or unsupported target, page size, or continuation token.
• NOT_FOUND: The requested instance or space does not exist.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the target, or the pagination token belongs to a different authenticated requestor.
• INTERNAL: Unexpected server or database failure.

Idempotency: Read-only and safe to retry. Concurrent policy changes may alter later pages.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{
"assigned_resource": { "space_id": "BASE64_ENCODED_SPACE_UUID" },
"include_revoked": true,
"max_results": 50
}' \
localhost:8080 goodmem.v1.AccessPolicyService/ListRoleAssignments

RevokeRoleAssignment

Permanently revokes one non-ROOT role assignment while preserving its audit history.

Auth: gRPC metadata authorization: Bearer <api-key>

Authorization Required: MANAGE_ACCESS on the assignment's instance or space target.

Request Behavior:

• role_assignment_id must identify an existing current or historical assignment.
• ROOT assignments cannot be revoked through this API because they mirror instance ownership.
• Revoking an already-revoked assignment succeeds without changing its original revocation timestamp or actor.
• The target must still exist, and the caller must retain authority on that target.

Response: The historical RoleAssignment, including revocation time and actor.

Side Effects: On the first successful call, records revoked_at and the exact authenticated principal or API key as revoked_by_id. The assignment row is never physically deleted.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication.
• INVALID_ARGUMENT: Malformed assignment UUID, or an authorized attempt to revoke ROOT.
• NOT_FOUND: The role assignment or its assigned resource does not exist.
• PERMISSION_DENIED: Caller lacks MANAGE_ACCESS on the assigned resource.
• INTERNAL: Unexpected server or database failure.

Idempotency: Authorized retries preserve and return the original revocation provenance.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <api-key>' \
-d '{ "role_assignment_id": "BASE64_ENCODED_ROLE_ASSIGNMENT_UUID" }' \
localhost:8080 goodmem.v1.AccessPolicyService/RevokeRoleAssignment

Messages

AccessPolicyTarget

A strongly typed GoodMem resource target.

The instance branch resolves to the singleton row in this database. UUID branches contain exactly 16 bytes. Identical UUID values in different branches remain distinct resources. When this message is supplied, exactly one target branch is required.

AccessPolicyRule

One typed authorization descriptor.

GrantAudience

Audience receiving one direct authorization grant; exactly one branch is required.

AuthorizationGrant

Current or historical direct authorization grant.

RoleAssignment

Current or historical assignment of one code-defined role.

CreateAuthorizationGrantRequest

GetAuthorizationGrantRequest

ListAuthorizationGrantsRequest

ListAuthorizationGrantsResponse

RevokeAuthorizationGrantRequest

AssignRoleRequest

GetRoleAssignmentRequest

ListRoleAssignmentsRequest

ListRoleAssignmentsResponse

RevokeRoleAssignmentRequest

AuthorizationCheck

One concrete, advisory authorization check for the authenticated request principal.

CheckAuthorizationsRequest

Request to evaluate a bounded set of concrete authorization checks.

AuthorizationCheckResult

One positional result for a concrete authorization check.

CheckAuthorizationsResponse

Response containing exactly one decision for every request check, in request order.

ListAuthorizationGrantsNextPageToken

Opaque grant-page cursor encoded and validated by the server.

ListRoleAssignmentsNextPageToken

Opaque role-assignment page cursor encoded and validated by the server.

Enums

AccessPolicyResourceKind

Concrete resource kinds accepted by GoodMem access policies.

Numeric values are stable persistence contracts shared with PostgreSQL and the Java authorization implementation. Values must never be renumbered or reused.

AccessPolicyOperation

Stable operations that may appear in authorization rules.

Numeric values are identical to the migration-managed operation catalog. An operation may only be paired with a compatible target kind and selector.

AccessPolicySelector

Resource-selection semantics for one authorization operation.

BuiltInRole

Code-defined roles assignable through the access-policy service.