Blinkin Legacy Docs Docs
PRDs · prds/01-auth-tenancy-prd.md Docs Home

PRD 01: Auth, Tenancy, Users, and Permissions

Problem Statement

The legacy platform supports authenticated workspace users, org context, tenant users, invites, external/public users, and protected companion access. These capabilities are split between Studio API and Zweistein and rely on manual checks in many service methods.

The new platform must preserve identity and tenancy behavior while making tenant boundaries harder to accidentally bypass.

Solution

Create a platform identity layer that supports:

  • Auth0/JWT login for internal users;
  • tenant/org context from the authenticated token;
  • tenant users, roles, invites, profile settings, and org switching;
  • external users and external groups for published companions;
  • public/anonymous access when explicitly configured;
  • password or external-user protection for companions;
  • audit logs for security-relevant access.

Legacy Source References

  • studio-api-reference/src/modules/studio/modules/auth/
  • studio-api-reference/src/common/services/passport-configration.service.ts
  • studio-api-reference/src/common/decorators/
  • studio-api-reference/src/core/guards/
  • studio-api-reference/src/modules/studio/modules/tenant/
  • studio-api-reference/src/modules/studio/modules/tenant-user/
  • studio-api-reference/src/database/entities/flow-protection.entity.ts
  • zweistein-reference/server/src/external-auth/
  • zweistein-reference/server/src/authz/

User Stories

  1. As a workspace user, I want to log in with a secure identity provider, so that I can access my organization safely.
  2. As a workspace user, I want the app to remember my current organization, so that I do not accidentally edit another tenant's data.
  3. As an org admin, I want to invite users, so that teammates can join the workspace.
  4. As an org admin, I want roles and permissions, so that only allowed users can manage billing, integrations, and publication.
  5. As an org admin, I want to remove or deactivate users, so that former team members lose access.
  6. As a creator, I want to protect a companion with a password, so that only intended users can access it.
  7. As a creator, I want to restrict a companion to external users or groups, so that customer-specific flows stay private.
  8. As an external user, I want a simple login path, so that I can use a shared companion without becoming an internal workspace user.
  9. As an external user, I want my session to expire predictably, so that access is secure.
  10. As a security owner, I want every request scoped to a tenant automatically, so that developers do not rely on manual checks.
  11. As an operator, I want authentication failures and suspicious access logged, so that abuse can be investigated.
  12. As a product designer, I want auth errors to be understandable, so that users know whether they need login, permission, or a different org.

Functional Requirements

Internal Auth

  • Support JWT validation with JWKS caching.
  • Extract user identity and org context from the token.
  • Create or sync local tenant-user records when a valid user first logs in.
  • Support profile settings and current organization selection.
  • Support HTTP and WebSocket or realtime auth paths.

Tenant Boundary

  • Every protected API request must have a tenant context.
  • Tenant context must be injected centrally, not recreated in each service method.
  • Data access must default to tenant-scoped queries.
  • Admin/super-admin exceptions must be explicit and auditable.

Roles and Permissions

  • Support at least owner, admin, member, viewer, and external user roles.
  • Permissions must gate billing, integrations, user management, publish settings, and data export.
  • Role checks must be testable without hitting external Auth0.

External Users

  • Support external users and groups.
  • Support login with a distinct token type from internal users.
  • Support audit logging for external login attempts.
  • Support companion-level access grants.
  • Rate-limit anonymous or public token creation.

Flow Protection

  • Support public, password-protected, and external-user-protected access modes.
  • Store password hashes, not plaintext passwords.
  • Support rate limiting for password attempts.
  • Support future temporary links and expiration.

Non-Functional Requirements

  • No hardcoded fallback secrets.
  • No unauthenticated token-minting endpoint without throttling.
  • No service-layer pattern where every method manually checks org ID.
  • Auth errors should use proper HTTP status codes.
  • Security logs must include request ID, tenant ID when known, actor ID, and failure reason.

Implementation Decisions

  • Build an AuthValidationService from the Studio API auth pattern.
  • Build a TenantBoundaryGuard that injects tenant context before business logic runs.
  • Build a decorator suite for current user, tenant, roles, and external user.
  • Keep external user auth as a separate identity path.
  • Keep flow protection as a separate relation from the flow/companion record.

Testing Decisions

  • Unit-test JWT payload parsing and tenant context extraction.
  • API-test every protected route for missing token, wrong tenant, wrong role, and valid access.
  • Integration-test external user login and protected companion access.
  • Abuse-test anonymous token generation and password attempts for throttling.

Out of Scope

  • Building a new identity provider.
  • Migrating production users before a data migration PRD exists.
  • Editing legacy repos.