Auth Module Overview

Purpose

Define a secure, maintainable App-based authentication and authorization model for SimBiz 6 API V3.

Scope Status

• This page is a design specification for the App-based auth hardening workstream.
• Runtime source implementation is tracked separately under APIV3-020.

Current State (Observed in Repository)

• V3 public token endpoint is POST /api/v3/auth/token (source-code/simbiz6/modules/simantz/apiv3/module.php).
• Token issuance validates client_id + client_secret and app/org scope before issuing app token (source-code/simbiz6/modules/simantz/apiv3/AuthAppController.php).
• Request authentication supports app-token context and permission/org checks in guard/middleware (source-code/simbiz6/apiv3/Auth/TokenGuard.php, source-code/simbiz6/apiv3/Auth/PermissionGuard.php).
• Router currently supports only requiresAuth boolean per route, with no permission key metadata (source-code/simbiz6/apiv3/Core/Router.php).

Target Model Summary

• Authenticate external integrations as Apps, not shared user secrets.
• Issue opaque DB-backed bearer tokens scoped to app + organization access.
• Enforce authorization in two layers:
  • route permission (resource-action)
  • organization access (allowed org list)
• Support secret lifecycle operations:
  • create
  • rotate (with optional grace)
  • revoke
  • audit
• Provide introspection endpoint so callers can read current app profile, scopes, org access, and token expiry.

Core Components

Component	Responsibility
App Registry	Store app identity, status, client_id, metadata
Secret Manager	Hash, rotate, revoke app secrets with history
Token Service	Issue/revoke opaque tokens and enforce expiry
Permission Catalog	Define resource-action permissions independent from URL
Route Permission Map	Map each route key to one permission code
Org Access Control	Restrict app usage to assigned organizations
Audit Log	Track auth/security events for traceability

Decision Matrix

Decision Point	Recommendation	Reason
1) Permission by raw path vs resource-action	Use resource-action permission codes + route map	Stable even when URL path changes
2) App to organization linking	Use explicit app-org mapping table	Supports single-org and multi-org apps safely
3) Secret regeneration model	Create new secret version; old secret can enter grace	Safer rotation without sudden outage
4) Old secret validity during rotation	Default grace 24h, configurable, allow immediate revoke	Operationally safe + security control
5) Token type	Opaque DB-backed token	Immediate revoke, simpler in PHP 7.3 legacy stack
6) Immediate revoke enforcement	Validate token against DB on every request	Real-time suspension/revocation behavior
7) Permission inspection endpoint	GET /api/v3/auth/me + GET /api/v3/auth/me/permissions	Third-party can verify granted access quickly
8) Check enforcement location	Central auth middleware/guard before controller	Avoid duplicated checks in every controller

Why Opaque DB Token (Not JWT)

Criteria	Opaque DB Token	JWT
Immediate revoke/suspend	Strong (DB status check)	Weak without blacklist
Rotation complexity	Low	Medium/high (key mgmt + invalidation complexity)
Legacy PHP 7.3 fit	Strong	Medium
Operational debugging	Strong (lookup in DB)	Medium
Stateless performance	Medium	Strong

Recommendation: use opaque DB-backed token for SimBiz 6 V3, prioritizing enforceable revoke/suspend and maintainability.

Request Validation Flow (High Level)

1. Read Authorization: Bearer <token>.
2. Hash token and find active token session.
3. Validate app status (ACTIVE).
4. Resolve route key and required permission.
5. Validate app has required permission.
6. Resolve target organization from request payload/query.
7. Validate organization is assigned to app.
8. Attach auth_context (app_id, app_code, token_id, organization_id, permissions) to request.
9. Continue to module controller.

Status Values (Recommended)

• App status: ACTIVE, SUSPENDED, REVOKED, EXPIRED
• Secret status: ACTIVE, GRACE, REVOKED, EXPIRED
• Token status: ACTIVE, REVOKED, EXPIRED

Compatibility Notes

• V3 endpoint is /api/v3/auth/token.
• x-uid is not required for external app authentication.