Protocol Documentation

Table of Contents

• housecarl_lib/proto/housecarl.proto

  • CheckAuthorizationRequest

  • CheckAuthorizationRequest.ContextEntry

  • CheckAuthorizationResponse

  • ClearUserAttributesRequest

  • CreateApiKeyRequest

  • CreateApiKeyResponse

  • CreateDomainRequest

  • CreateEmailVerificationTokenRequest

  • CreateEmailVerificationTokenResponse

  • CreateOAuthUserRequest

  • CreateOAuthUserResponse

  • CreateServiceAccountRequest

  • CreateServiceAccountResponse

  • CreateTenantRequest

  • CreateTenantUserAssociationRequest

  • CreateUserRequest

  • CreateUserResponse

  • DeleteApiKeyRequest

  • DeleteDomainRequest

  • DeleteServiceAccountRequest

  • DeleteTenantRequest

  • DeleteTenantUserAssociationRequest

  • DeleteUserRequest

  • Domain

  • FindUserByOAuthRequest

  • FindUserByOAuthResponse

  • GetApiKeyRequest

  • GetApiKeyResponse

  • GetDomainByNameRequest

  • GetDomainPoliciesRequest

  • GetDomainPoliciesResponse

  • GetDomainRequest

  • GetServiceAccountRequest

  • GetTenantAssociationsRequest

  • GetTenantAssociationsResponse

  • GetTenantByNameRequest

  • GetTenantRequest

  • GetTenantUserAssociationRequest

  • GetTenantUserAssociationResponse

  • GetUserAttributesRequest

  • GetUserAttributesResponse

  • GetUserAttributesResponse.AttributesEntry

  • GetUserByNameRequest

  • GetUserRequest

  • IsLoggedInRequest

  • IsLoggedInResponse

  • ListServiceAccountsRequest

  • ListServiceAccountsResponse

  • ListTenantsRequest

  • ListTenantsResponse

  • ListUsersRequest

  • ListUsersResponse

  • LoginRequest

  • LoginResponse

  • LogoutRequest

  • MarkEmailVerifiedRequest

  • Policy

  • PolicyStatement

  • PolicyStatement.RulesEntry

  • PutDomainPoliciesRequest

  • RefreshLoginWithTenantRequest

  • RefreshTenantsRequest

  • RemoveUserAttributeRequest

  • RequestValue

  • ServiceAccount

  • SetUserAttributeRequest

  • StoreOAuthStateRequest

  • StringArray

  • Tenant

  • Tokens

  • UpdateDomainRequest

  • UpdateServiceAccountRequest

  • UpdateTenantRequest

  • UpdateUserRequest

  • User

  • ValidateEmailVerificationTokenRequest

  • ValidateEmailVerificationTokenResponse

  • ValidateOAuthStateRequest

  • ValidateOAuthStateResponse

  • EvaluationEngine

  • TokenType

  • HousecarlService

• housecarl_lib/proto/healthz.proto

  • HealthCheckRequest

  • HealthCheckResponse

  • HealthCheckResponse.ServingStatus

  • Health

• housecarl_lib/proto/jwt.proto

  • GetPublicKeyRequest

  • GetPublicKeyResponse

  • JwtService

• Scalar Value Types

housecarl_lib/proto/housecarl.proto

CheckAuthorizationRequest

CheckAuthorizationRequest evaluates if an action is allowed

This is the core authorization check that evaluates policies against a request. The request context is a map of string key-value pairs that describe the authorization request.

REQUIRED CONTEXT KEYS:

• "subject": The entity performing the action (e.g., "user:alice@example.com")
• "action": The operation being attempted (e.g., "read", "write", "delete")
• "object": The resource in hc:// URI format (e.g., "hc://550e8400-e29b-41d4-a716-446655440000/documents/report.pdf")

The "object" value MUST be a valid hc:// URI where the domain UUID is used to identify which domain's policies apply. The domain UUID must exist and be accessible by the tenant in the JWT token.

OPTIONAL CONTEXT KEYS:

You can include any additional context attributes that your policies need:

• "time": Request timestamp (RFC3339 format)
• "ip_address": Client IP address
• "user_agent": Client user agent string
• "owner": Resource owner identifier
• "department": User's department
• "clearance_level": Security clearance
• Any custom application-specific attributes

EVALUATION PROCESS:

1. Extract domain UUID from object hc:// URI
2. Retrieve domain and all superior domains
3. Collect all policies from domain hierarchy
4. Evaluate each policy against context using policy's engine
5. Apply invert and deny flags
6. Return authorized=true if at least one allow and no denies
7. Return authorized=false if any deny or no allows (default deny)

EXAMPLE REQUEST:

{ "context": { "subject": "user:alice@example.com", "action": "read", "object": "hc://550e8400-e29b-41d4-a716-446655440000/documents/report.pdf", "time": "2024-01-15T10:30:00Z", "ip_address": "192.168.1.100", "owner": "user:alice@example.com" } }

This would match a policy like: { "engine": EVALUATION_ENGINE_PREFIX, "statements": [{ "rules": { "action": "read", "object": "hc://550e8400-e29b-41d4-a716-446655440000/documents/" } }] }

POLICY MACRO EVALUATION:

If policies contain macros (e.g., $current_user()), they are evaluated using information from:

• JWT token (user_id, tenant_id)
• Request context (custom attributes)
• System state (current time, etc.)

For example, a policy with: {"subject": "$current_user()", "owner": "$resource_owner()"} Would expand at evaluation time to: {"subject": "user:alice@example.com", "owner": "user:alice@example.com"} And match if both values are equal.

ERROR CASES:

Returns gRPC error if:

• Missing required context keys (subject, action, object)
• Invalid hc:// URI format in object
• Domain UUID not found or not accessible
• JWT token invalid or missing
• Tenant in JWT doesn't match domain's tenant

CheckAuthorizationRequest.ContextEntry

CheckAuthorizationResponse

CheckAuthorizationResponse returns the authorization decision

The authorized field indicates whether the request should be allowed.

INTERPRETATION:

authorized = true:

• At least one policy allowed the request
• No policies denied the request
• The action should be permitted

authorized = false:

• Either no policies matched (default deny)
• Or at least one policy denied the request (deny overrides allow)
• The action should be rejected

APPLICATION INTEGRATION:

After receiving the response, your application should:

1. Check the authorized field
2. If true, proceed with the requested operation
3. If false, reject the operation and return 403 Forbidden to the client
4. Log the authorization decision for audit purposes

PERFORMANCE CONSIDERATIONS:

• CheckAuthorization calls are designed to be fast (sub-millisecond typical)
• Results can be cached for short periods (seconds to minutes)
• Cache keys should include all context attributes used in policies
• Invalidate cache when policies are updated

AUDIT LOGGING:

All CheckAuthorization calls should be logged to the audit service with:

• Timestamp
• Subject (from context)
• Action (from context)
• Object (from context)
• Result (authorized true/false)
• Tenant ID (from JWT)
• Request ID (for correlation)

ClearUserAttributesRequest

ClearUserAttributesRequest removes all attributes for a user in the current tenant

CreateApiKeyRequest

CreateApiKeyResponse

CreateDomainRequest

CreateEmailVerificationTokenRequest

CreateEmailVerificationTokenResponse

CreateOAuthUserRequest

CreateOAuthUserResponse

CreateServiceAccountRequest

CreateServiceAccountResponse

CreateTenantRequest

Request to create a new tenant. See CreateTenant RPC documentation for details on the bootstrap behavior that occurs when a tenant is created (automatic domain, policies, and user association).

CreateTenantUserAssociationRequest

CreateUserRequest

CreateUserResponse

DeleteApiKeyRequest

DeleteDomainRequest

DeleteServiceAccountRequest

DeleteTenantRequest

DeleteTenantUserAssociationRequest

DeleteUserRequest

Domain

Domain represents a policy container within a tenant Domains can be hierarchical through superior_domain_ids

FindUserByOAuthRequest

FindUserByOAuthResponse

GetApiKeyRequest

GetApiKeyResponse

GetDomainByNameRequest

GetDomainPoliciesRequest

GetDomainPoliciesResponse

GetDomainRequest

GetServiceAccountRequest

GetTenantAssociationsRequest

GetTenantAssociationsResponse

GetTenantByNameRequest

GetTenantRequest

GetTenantUserAssociationRequest

GetTenantUserAssociationResponse

GetUserAttributesRequest

GetUserAttributesRequest retrieves all attributes for a user in the current tenant

GetUserAttributesResponse

GetUserAttributesResponse returns all attributes grouped by key

GetUserAttributesResponse.AttributesEntry

GetUserByNameRequest

GetUserRequest

IsLoggedInRequest

JWT will be passed in request headers No body needed - authentication via Bearer token

IsLoggedInResponse

ListServiceAccountsRequest

ListServiceAccountsResponse

ListTenantsRequest

Empty for now, could add pagination later

ListTenantsResponse

ListUsersRequest

Empty for now, could add pagination later

ListUsersResponse

LoginRequest

LoginResponse

LogoutRequest

MarkEmailVerifiedRequest

Policy

Policy defines authorization rules for resources

A policy is a named set of rules that determine whether a request should be allowed or denied. Policies are attached to domains and evaluated during CheckAuthorization calls.

POLICY EVALUATION:

During CheckAuthorization, each policy is evaluated as follows:

1. For each statement in the policy: a. Check if all statement keys exist in request context b. Match statement values against context values using the engine c. If all keys match, the statement matches
2. If ANY statement matches: a. Apply invert flag: if true, flip the result (match→no match, no match→match) b. Track as DENY if deny=true, otherwise as ALLOW c. Continue to next policy
3. After all policies evaluated: a. If ANY DENY, return authorized=false b. If NO DENY and at least one ALLOW, return authorized=true c. If NO policies matched, return authorized=false (default deny)

POLICY FLAGS:

invert: Reverses the match result

• Use for "everyone except" scenarios
• Example: Allow all users except contractors
• Set invert=true with contractor user pattern

deny: Makes this a deny policy (overrides allows)

• Use for security boundaries and restrictions
• Example: Deny all access to /admin/* for non-admins
• Deny policies always win over allow policies

BEST PRACTICES:

1. Keep policies simple and focused on a single concern
2. Use descriptive names that indicate the policy's purpose
3. Document complex policies in the description field
4. Prefer simpler engines (FIXED, PREFIX) over complex ones (REGEX)
5. Use deny policies sparingly for security-critical restrictions
6. Test policies thoroughly before deployment

POLICY EXAMPLES:

Allow read access to documents: { "name": "read-documents", "description": "Allow users to read documents", "invert": false, "deny": false, "engine": EVALUATION_ENGINE_PREFIX, "statements": [{ "rules": { "action": "read", "object": "hc://550e8400-e29b-41d4-a716-446655440000/documents/" } }] }

Deny access to sensitive resources: { "name": "deny-sensitive", "description": "Prevent access to sensitive resources", "invert": false, "deny": true, "engine": EVALUATION_ENGINE_PREFIX, "statements": [{ "rules": { "object": "hc://550e8400-e29b-41d4-a716-446655440000/sensitive/" } }] }

Allow owner-only access using macros: { "name": "owner-access", "description": "Users can only access resources they own", "invert": false, "deny": false, "engine": EVALUATION_ENGINE_FIXED, "statements": [{ "rules": { "subject": "$current_user()", "owner": "$resource_owner()" } }] }

PolicyStatement

PolicyStatement contains the actual rules to evaluate

A statement is a set of key-value pairs that must ALL match the request context for the statement to match (AND logic).

STATEMENT MATCHING:

For a statement to match:

1. Every key in rules must exist in the request context
2. Every value must match according to the policy's engine
3. Request context may have additional keys (they are ignored)

EXAMPLE:

Policy statement: { "rules": { "action": "read", "object": "hc://550e8400-e29b-41d4-a716-446655440000/documents/" } }

Request context (matches): { "subject": "user:alice@example.com", // ignored (not in rules) "action": "read", // matches "object": "hc://550e8400-e29b-41d4-a716-446655440000/documents/report.pdf" // matches (PREFIX engine) }

Request context (does NOT match): { "action": "write", // does not match (not "read") "object": "hc://550e8400-e29b-41d4-a716-446655440000/documents/report.pdf" }

MULTIPLE STATEMENTS:

Use multiple statements in a policy for OR logic: { "statements": [ {"rules": {"action": "read"}}, {"rules": {"action": "write"}} ] } This matches requests with action="read" OR action="write"

PolicyStatement.RulesEntry

PutDomainPoliciesRequest

RefreshLoginWithTenantRequest

RefreshLoginWithTenantRequest transmutes a tenantless login to a tenantful one

USAGE SCENARIO:

1. User logs in without tenant parameter → receives JWT with no tenant_id claim
2. User creates a tenant (becomes associated via CreateTenant)
3. User calls RefreshLoginWithTenant to upgrade session
4. Server validates association and issues new JWT with tenant_id claim

SECURITY:

• Requires valid JWT token in request headers (authentication)
• Current JWT MUST NOT have a tenant_id claim (can only transmute tenantless → tenantful)
• Verifies user is associated with requested tenant via TenantsUserLink
• Returns PERMISSION_DENIED if user is not associated
• Returns FAILED_PRECONDITION if current JWT already has a tenant

RESPONSE:

Returns LoginResponse with new JWT containing:

• Same user_id as current JWT
• tenant_id claim set to requested tenant
• User attributes for the tenant included in JWT
• New expiration timestamp (default 12 hours from now)

RefreshTenantsRequest

Empty - refreshes tokens for all tenants

RemoveUserAttributeRequest

RemoveUserAttributeRequest removes attribute values for a user in the current tenant

RequestValue

RequestValue supports both single and multi-valued context attributes Used in CheckAuthorizationRequest for multi-valued attribute matching

ServiceAccount

SetUserAttributeRequest

SetUserAttributeRequest adds attribute values for a user in the current tenant

StoreOAuthStateRequest

StringArray

StringArray holds multiple string values for a single key

Tenant

Tenant represents a top-level organizational unit All resources are isolated by tenant

Tokens

API call tracking for rate limiting

Housecarl uses a token bucket algorithm for rate limiting based on API calls. Each operation consumes one call, and the call quota is replenished during RefreshTenants operations. "Calls" represents the most technically accurate and user-controllable measure of system usage.

CALL CONSUMPTION:

When an operation is performed:

1. If available calls >= 1, decrement by 1 and allow the operation
2. If calls < 1 and overage < max_overage, increment overage and allow
3. If calls < 1 and overage >= max_overage, reject with RESOURCE_EXHAUSTED

CALL QUOTA REFRESH:

Call RefreshTenants periodically (e.g., hourly, daily) to reset:

• calls = max_calls (replenish to maximum)
• overage = 0 (reset burst usage)

RATE LIMIT TYPES:

Tenants have two separate call quotas:

• control_plane: For management operations (CreateUser, CreateDomain, etc.)
• data_plane: For authorization checks (CheckAuthorization)

Users have a separate quota:

• user_plane: For user-initiated operations

BURST CAPACITY:

max_overage allows temporary bursts above max_calls. This is useful for handling traffic spikes without immediately rejecting requests.

Example: max_calls=1000, max_overage=500

• Steady state: Up to 1000 operations per refresh cycle
• Burst capacity: Up to 1500 operations (1000 + 500 overage)
• After burst: Next refresh resets both call quota and overage

UpdateDomainRequest

UpdateServiceAccountRequest

UpdateTenantRequest

UpdateUserRequest

User

User represents an authenticated entity that can access tenants

ValidateEmailVerificationTokenRequest

ValidateEmailVerificationTokenResponse

ValidateOAuthStateRequest

ValidateOAuthStateResponse

EvaluationEngine

Policy evaluation engine types

The evaluation engine determines how policy statement rules are matched against the request context during authorization checks.

All engines operate on key-value pairs where both keys and values are strings. The request context is matched against policy statement rules according to the selected engine's matching semantics.

MATCHING LOGIC:

For a policy statement to match:

1. All keys in the policy statement must exist in the request context
2. The values must match according to the engine's rules
3. Request context may contain additional keys (they are ignored)

EXAMPLE REQUEST CONTEXT: { "subject": "user:alice@example.com", "action": "read", "object": "hc://550e8400-e29b-41d4-a716-446655440000/documents/report.pdf", "time": "2024-01-15T10:30:00Z", "ip_address": "192.168.1.100" }

TokenType

HousecarlService

Domain operations Domains are hierarchical policy containers within a tenant

housecarl_lib/proto/healthz.proto

HealthCheckRequest

HealthCheckResponse

HealthCheckResponse.ServingStatus

Health

housecarl_lib/proto/jwt.proto

GetPublicKeyRequest

Request to get JWT public key

Empty request - the public key is the same for all callers

GetPublicKeyResponse

Response containing JWT public key information

JwtService

JWT key management service for external service integration Provides public key distribution for JWT token verification

Scalar Value Types