Passport Data Model

Passport manages three primary entities: Providers, Authorizations, and Audit Entries. All entities use nanoid(8) identifiers and support both file-based and Convex storage backends.

Provider

Represents a registered OAuth provider with its client configuration.

interface Provider {
  id: string;           // nanoid(8) unique identifier
  name: string;         // Human-readable provider name (e.g., "github")
  type: string;         // Provider type (e.g., "oauth2")
  clientId: string;     // OAuth client ID
  scopes: string[];     // Available scopes for this provider
  redirectUri: string;  // OAuth redirect URI
  createdAt: string;    // ISO 8601 timestamp
}

Authorization

A granted authorization linking a user to a provider with specific scopes and a token.

interface Authorization {
  id: string;           // nanoid(8) unique identifier
  providerId: string;   // Reference to the Provider
  userId: string;       // The user this authorization belongs to
  scopes: string[];     // Granted scopes (subset of provider's available scopes)
  token: string;        // OAuth access token
  expiresAt: string;    // ISO 8601 timestamp for token expiration
  createdAt: string;    // ISO 8601 timestamp
}

AuditEntry

An immutable record of an authorization-related action.

interface AuditEntry {
  id: string;           // nanoid(8) unique identifier
  action: string;       // Action type (e.g., "authorization.created", "authorization.revoked")
  providerId: string;   // Reference to the Provider involved
  userId: string;       // The user who performed or was subject to the action
  timestamp: string;    // ISO 8601 timestamp
}

Audit Actions

Action	Description
authorization.created	A new authorization was granted
authorization.revoked	An authorization was revoked
authorization.refreshed	An authorization token was refreshed
provider.created	A new provider was registered
provider.deleted	A provider was removed

Storage

File-Based (SHIFT_STORAGE=file)

.passport/
  providers/
    <id>.json           # One file per provider
  authorizations/
    <id>.json           # One file per authorization
  audit/
    <id>.json           # One file per audit entry

Convex (SHIFT_STORAGE=convex)

Tables use the passport_ prefix:

Table	Description
passport_providers	Provider records
passport_authorizations	Authorization records
passport_audit	Audit trail entries

Each record includes a sid field (shift ID) that maps to the application-level id. Convex internal _id fields are abstracted away by the ConvexStore layer.