app/ts_interfaces/readme.md

# @idp.global/interfaces

TypeScript interfaces and type definitions for the idp.global Identity Provider platform.

## Overview

This package provides the complete type system for idp.global, including data models, API request/response interfaces, and OIDC definitions. Use this package when building applications that integrate with idp.global or when you need type-safe interactions with the IdP API.

## Installation

```bash
npm install @idp.global/interfaces
# or
pnpm add @idp.global/interfaces
```

## Usage

```typescript
import { data, request, tags } from '@idp.global/interfaces';

// Data interfaces
const user: data.IUser = {
  id: 'user_123',
  data: {
    name: 'John Doe',
    username: 'johndoe',
    email: 'john@example.com',
    status: 'active',
    connectedOrgs: ['org_1', 'org_2'],
  },
};

// Organization interface
const org: data.IOrganization = {
  id: 'org_1',
  data: {
    name: 'Acme Corp',
    slug: 'acme',
    billingPlanId: 'plan_free',
    roleIds: ['role_admin', 'role_member'],
  },
};
```

## Package Structure

```
ts_interfaces/
├── data/                    # Data model interfaces
│   ├── loint-reception.user.ts         # User profiles
│   ├── loint-reception.organization.ts # Organizations
│   ├── loint-reception.role.ts         # RBAC roles
│   ├── loint-reception.app.ts          # OAuth applications
│   ├── loint-reception.oidc.ts         # OIDC tokens & flows
│   ├── loint-reception.jwt.ts          # JWT structures
│   ├── loint-reception.loginsession.ts # Login sessions
│   ├── loint-reception.billingplan.ts  # Billing plans
│   ├── loint-reception.device.ts       # Device management
│   ├── loint-reception.activity.ts     # Activity logs
│   ├── loint-reception.userinvitation.ts # Invitations
│   └── loint-reception.appconnection.ts  # App connections
├── request/                 # API request/response interfaces
│   ├── loint-reception.login.ts        # Authentication
│   ├── loint-reception.registration.ts # User registration
│   ├── loint-reception.user.ts         # User management
│   ├── loint-reception.organization.ts # Org management
│   ├── loint-reception.jwt.ts          # JWT operations
│   ├── loint-reception.apitoken.ts     # API tokens
│   ├── loint-reception.app.ts          # App management
│   ├── loint-reception.billingplan.ts  # Billing
│   └── loint-reception.admin.ts        # Admin operations
└── tags/                    # Tag definitions
```

## Data Interfaces

### User (`IUser`)

```typescript
interface IUser {
  id: string;
  data: {
    name: string;
    username: string;
    email: string;
    mobileNumber?: string;
    password?: string;        // Only during initial setting
    passwordHash?: string;    // For validation
    status: 'new' | 'active' | 'deleted' | 'suspended';
    connectedOrgs: string[];  // Organization IDs
    isGlobalAdmin?: boolean;  // Platform admin flag
  };
}
```

### Organization (`IOrganization`)

```typescript
interface IOrganization {
  id: string;
  data: {
    name: string;
    slug: string;
    billingPlanId: string;
    roleIds: string[];
  };
}
```

### Role (`IRole`)

```typescript
interface IRole {
  id: string;
  data: {
    name: string;
    organizationId: string;
    userId: string;
    permissions: string[];
  };
}
```

### OAuth Application Types

```typescript
// Global platform apps (maintained by platform admins)
interface IGlobalApp {
  id: string;
  type: 'globalApp';
  data: {
    name: string;
    description: string;
    iconBase64?: string;
    oauthCredentials?: IOAuthCredentials;
  };
}

// Partner apps (third-party integrations)
interface IPartnerApp {
  id: string;
  type: 'partnerApp';
  data: {
    name: string;
    description: string;
    ownerOrganizationId: string;
    oauthCredentials?: IOAuthCredentials;
  };
}

// Custom OIDC clients
interface ICustomOidcApp {
  id: string;
  type: 'customOidcApp';
  data: {
    name: string;
    description: string;
    ownerOrganizationId: string;
    oauthCredentials: IOAuthCredentials;
  };
}
```

### OAuth Credentials

```typescript
interface IOAuthCredentials {
  clientId: string;
  clientSecretHash: string;
  redirectUris: string[];
  scopes: string[];
  grantTypes: ('authorization_code' | 'refresh_token' | 'client_credentials')[];
}
```

## OIDC Interfaces

### Authorization Code

```typescript
interface IAuthorizationCode {
  code: string;
  clientId: string;
  userId: string;
  scopes: string[];
  redirectUri: string;
  codeChallenge?: string;
  codeChallengeMethod?: 'S256';
  expiresAt: number;
  used: boolean;
}
```

### Token Response

```typescript
interface ITokenResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
  refresh_token?: string;
  id_token?: string;
  scope: string;
}
```

### UserInfo Response

```typescript
interface IUserInfoResponse {
  sub: string;
  name?: string;
  preferred_username?: string;
  email?: string;
  email_verified?: boolean;
  organizations?: Array<{
    id: string;
    name: string;
    slug: string;
    roles: string[];
  }>;
  roles?: string[];
}
```

### ID Token Claims

```typescript
interface IIdTokenClaims {
  iss: string;          // Issuer
  sub: string;          // Subject (user ID)
  aud: string;          // Audience (client ID)
  exp: number;          // Expiration time
  iat: number;          // Issued at
  nonce?: string;       // Replay protection
  name?: string;
  email?: string;
  email_verified?: boolean;
  organizations?: Array<{...}>;
  roles?: string[];
}
```

## Request Interfaces

All API requests follow the TypedRequest pattern:

```typescript
interface IReq_LoginWithEmailOrUsernameAndPassword {
  method: 'loginWithEmailOrUsernameAndPassword';
  request: {
    username: string;
    password: string;
  };
  response: {
    refreshToken?: string;
    twoFaNeeded: boolean;
  };
}
```

### Authentication Requests

| Interface | Method | Description |
|-----------|--------|-------------|
| `IReq_LoginWithEmailOrUsernameAndPassword` | `loginWithEmailOrUsernameAndPassword` | Password login |
| `IReq_LoginWithEmail` | `loginWithEmail` | Magic link request |
| `IReq_LoginWithEmailAfterEmailTokenAquired` | `loginWithEmailAfterEmailTokenAquired` | Magic link verification |
| `IReq_LoginWithApiToken` | `loginWithApiToken` | API token login |
| `IReq_RefreshJwt` | `refreshJwt` | Refresh access token |
| `ILogoutRequest` | `logout` | End session |

### User Management Requests

| Interface | Method | Description |
|-----------|--------|-------------|
| `IReq_GetUserData` | `getUserData` | Get current user |
| `IReq_SetUserData` | `setUserData` | Update user profile |
| `IReq_GetUserSessions` | `getUserSessions` | List active sessions |
| `IReq_ResetPassword` | `resetPassword` | Request password reset |
| `IReq_SetNewPassword` | `setNewPassword` | Set new password |

### Organization Requests

| Interface | Method | Description |
|-----------|--------|-------------|
| `IReq_CreateOrganization` | `createOrganization` | Create new org |
| `IReq_GetOrgMembers` | `getOrgMembers` | List org members |
| `IReq_CreateInvitation` | `createInvitation` | Invite user |
| `IReq_AcceptInvitation` | `acceptInvitation` | Accept invite |

### JWT Operations

| Interface | Method | Description |
|-----------|--------|-------------|
| `IReq_GetPublicKeyForValidation` | `getPublicKeyForValidation` | Get JWT public key |
| `IReq_GetJwtIdBlocklist` | `getJwtIdBlocklist` | Get revoked token IDs |

## Supported OIDC Scopes

| Scope | Description |
|-------|-------------|
| `openid` | Required for OIDC flows |
| `profile` | User's name and username |
| `email` | User's email address |
| `organizations` | User's organization memberships |
| `roles` | User's roles within organizations |

## License

MIT - See the main repository for full license details.