Skip to content

Sub-Domain Blueprint: Unified Identity

Domain: Unified (audit, communications, identity, library, notifications, search, signals, vault, workflow) Logical Sub-Domain: Identity & Access (IA) Physical Packages: @sd/mod-unified-identity Related Documents: Data Definition Context: This document defines the Process Models, Mandate, and Lifecycle Logic for Identity Management. Status: Stable (v2.5)

1. Mandate

The Identity Sub-Domain is the Gatekeeper of the Singular Dream platform. It manages the entire lifecycle of an actor (Resident, Staff, Vendor) from initial Access Request, through Verification (Forensic Proof), to Provisioning (Ascent), and finally Revocation (Descent).

2. Capabilities

Capability Description Component
Access Request Handling unauthenticated requests for account creation. AccessService
Forensic Vault Secure storage of ID proofs (Passport, Deeds) for verification. AccessService (Foundation Storage)
Identity Ascent Promoting a user from unverified to provisioned upon approval. LifecycleManager
Identity Descent Demoting a user (revoked, expired) and stripping roles. LifecycleManager
Context Resolution Mapping informal roles ("Owner") to formal Directory Contexts. resolveProfileContext

3. Process Models

A. Access Request (Onboarding)

Happy Path: A new Property Owner requests access.

sequenceDiagram
    participant User
    participant Service as AccessService
    participant Workflow as WorkflowEngine
    participant Storage as ForensicVault
    participant Admin

    User->>Service: upload(passport.pdf)
    Service->>Storage: requestUploadUrl()
    Storage-->>User: signedUrl
    User->>Storage: PUT file
    User->>Service: createRequest({ name, role: "Owner", docUrls: [...] })
    Service->>Workflow: createRequest(status: "submitted")
    Workflow-->>Admin: Notification(New Request)

    Admin->>Service: approveRequest(requestId)
    Service->>Registry: ensureProfile(email, type="resident")
    Service->>DB: User.update(roles=["owner"], lifecycle="provisioned")
    Service-->>User: Welcome Email

B. Identity Descent (Revocation)

Security removes a bad actor.

sequenceDiagram
    participant Admin
    participant Service as LifecycleManager
    participant Audit as ForensicAudit

    Admin->>Service: handleDescent(userId, "revoked", "Violation of Rules")
    Service->>DB: User.update(roles=[], state="revoked")
    Service->>Audit: log({ type: "IDENTITY_DESCENT", reason: "Violation..." })
    Service->>Admin: Confirm Revocation

4. State Machines

Identity Lifecycle (User.lifecycle.state)

stateDiagram-v2
    [*] --> Unverified: Request Submitted
    Unverified --> IdentityVerified: Doc Check Passed
    IdentityVerified --> Provisioned: Approved (Ascent)
    Provisioned --> Expired: Lease End / Timer
    Provisioned --> Revoked: Ban (Descent)
    Expired --> Provisioned: Renewal
    Revoked --> [*]: Permanent

5. Interface Definitions

AccessService

  • createRequest(userId, data): Promise<ServiceRequest>
  • approveRequest(requestId, adminId): Promise<void>
  • denyRequest(requestId, adminId): Promise<void>

LifecycleManager

  • handleAscent(userId, state, reason): Promise<void>
  • handleDescent(userId, state, reason): Promise<void>

6. Changelog

Date Author Description Reference
2026-01-24 Antigravity Initial creation Implementation Plan