← Back

Pharos Framework Identity, Tenancy, and Form Contracts

Pharos has to prove measured value over ordinary CRUD stacks on explainability and policy, not just on route generation. That requires explicit contracts for identity, sessions, team/tenant membership, forms, and validation.

Identity Contract

Every identity-bearing actor must specify:

• actor_kind
• identity_fields
• auth_modes
• session_modes
• tenant_membership_modes
• role_attachment_modes

Example shape:

{
  "actor_kind": "user",
  "identity_fields": ["id", "email", "password_hash", "display_name"],
  "auth_modes": ["session_password", "invite_acceptance", "password_reset"],
  "session_modes": ["browser_session", "api_session"],
  "tenant_membership_modes": ["organization_membership", "team_membership"],
  "role_attachment_modes": ["global_role", "tenant_role", "team_role"]
}

Session Contract

Every session surface must specify:

• session_kind
• cookie_or_token_mode
• expiry_policy
• revocation_mode
• current_actor_projection

Required session kinds:

• browser_session
• api_session
• invite_claim_session
• password_reset_session

Tenant Membership Contract

Every tenant-aware app must specify:

• tenant_entity
• membership_entity
• role_scope
• policy_scope
• data_scope_projection
• generated_admin_scope

Example shape:

{
  "tenant_entity": "organization",
  "membership_entity": "organization_membership",
  "role_scope": ["tenant_admin", "tenant_operator", "tenant_viewer"],
  "policy_scope": "tenant_bound",
  "data_scope_projection": "tenant_id required in all tenant-bound entities",
  "generated_admin_scope": "tenant_filtered"
}

Form Contract

Every form must specify:

• form_id
• target_entity
• submit_action
• field_set
• validation_rules
• error_shape
• csrf_mode
• html_api_parity_mode

Example shape:

{
  "form_id": "tenant_invoice_create_form",
  "target_entity": "tenant_invoice",
  "submit_action": "create_tenant_invoice",
  "field_set": ["title", "amount", "due_at"],
  "validation_rules": ["required:title", "required:amount", "date:due_at"],
  "error_shape": "field_errors + form_errors",
  "csrf_mode": "required_for_browser_session",
  "html_api_parity_mode": "same_validation_and_error_ids"
}

Validation Report Contract

Every failed validation must specify:

• report_id
• form_id
• action_id
• field_errors
• form_errors
• actor_scope
• tenant_scope

Required result property:

• the same validation rule ids must appear in HTML and JSON error surfaces

Policy/Tenancy Contract

Every protected action must specify:

• subject_scope
• tenant_scope
• team_scope
• requested_capability
• allow_deny_result
• explanation_path
• scope_projection

Pharos should reject:

• ambient admin powers not present in the graph
• tenant filtering implemented only in UI and not in policy/data contracts
• browser forms and JSON actions with different validation or policy behavior