Auth Implementation Notes

Purpose

Provide implementation guidance for developers to build the App-based auth model in SimBiz 6 API V3 safely under PHP 7.3 + MariaDB 10.11.

Scope Status

• This page defines implementation notes for the upcoming auth hardening phase.

Secret Storage Rule

• Never store plaintext client secret.
• Generate secret with random_bytes() and encode for transport.
• Store only hash:
  • password_hash($secret . ':' . APP_AUTH_PEPPER, PASSWORD_BCRYPT, ['cost' => 12])
• Verify with:
  • password_verify($providedSecret . ':' . APP_AUTH_PEPPER, $secretHash)
• Keep only secret_hint (masked last chars) for operator reference.
• Show new secret only once at create/rotate response.

Token Rule

• Token type: opaque bearer token.
• Generation example (PHP 7.3 safe):
  • $raw = bin2hex(random_bytes(32));
  • $accessToken = 'sbv3_' . $raw;
• Persist only hash:
  • $tokenHash = hash_hmac('sha256', $accessToken, APP_TOKEN_PEPPER);
• Store token_prefix for support troubleshooting (for example first 12 chars).

Token Expiry and Rotation Rule

• Default TTL from system_api3_config.TOKEN_TTL_SECONDS (suggested default: 3600).
• Max TTL guard from TOKEN_MAX_TTL_SECONDS.
• Secret rotation default grace from SECRET_GRACE_HOURS.
• Rotation behavior:
  1. create new ACTIVE secret version
  2. old ACTIVE -> GRACE until grace_until
  3. after grace, old secret -> EXPIRED or REVOKED
• Admin may force immediate revoke (grace_hours = 0).

Revoke and Suspend Behavior

• SUSPENDED app:
  • deny new token issuance
  • deny API calls for active tokens immediately
• REVOKED app:
  • deny issuance and access
  • revoke all active tokens immediately
• Token revoke must be enforced in middleware by DB check per request.

Permission Check Strategy

• Do not check permissions inside each controller action manually.
• Centralize in auth guard middleware:
  1. resolve route key
  2. resolve required permission
  3. verify grant in system_api3_app_permission
  4. fail fast with 403

Organization Validation Strategy

• Resolve effective org from request:
  • query: organization_id/org_id, organization_code/org_code
  • body: same keys for create/update
  • fallback: token org context, then app default org
• Validate resolved org exists in system_api3_app_organization and is active.
• Reject unresolved org with 400; reject unauthorized org with 403.

Audit Logging Recommendations

Log at minimum these events to system_api3_audit_log:

• TOKEN_ISSUED
• TOKEN_REVOKED
• APP_SUSPENDED
• APP_REACTIVATED
• APP_REVOKED
• SECRET_ROTATED
• PERMISSION_DENIED
• ORG_DENIED

Include context: app, token, route key, reason code, actor uid, IP, user-agent.

Integration with Current V3 Structure

Observed V3 core files:

• source-code/simbiz6/apiv3/Core/Router.php
• source-code/simbiz6/apiv3/Auth/TokenGuard.php
• source-code/simbiz6/api_v3.php

Recommended extension path:

1. Extend router metadata to include route_key (and optionally required permission code).
2. Replace current TokenGuard with AppTokenGuard that validates:
   • token
   • app status
   • permission
   • organization access
3. Keep module route declarations in modules/*/apiv3/module.php to preserve module-first ownership.
4. Introduce auth admin endpoints in modules/simantz/apiv3 or dedicated modules/auth/apiv3.

Backward Compatibility Plan

1. Use POST /api/v3/auth/token as the only V3 token issuance endpoint.
2. Add migration script to bootstrap app records for existing integrations.
3. Communicate cutoff date for legacy user-secret integrations.
4. Disable legacy user-secret token issuance path.

Security Checklist Before Go-Live

• Secrets hashed with pepper and never logged.
• Tokens stored as hash only.
• Permission denial returns standardized 403 errors.
• Organization access checked for every protected endpoint.
• App suspend/revoke takes effect immediately.
• Audit log captures auth-critical events.
• Rotation and revoke tested with live-like data.
• Wiki and API spec updated in same change set.