Skip to content

feat(admin): implement security audit logging and outbound webhooks event system #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AmanKrSahu merged 2 commits into from
Sep 4, 2026
Merged

feat(admin): implement security audit logging and outbound webhooks event system #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d80ed5e
feat(admin): implemented security audit logs feature and admin apis
AmanKrSahu Aug 22, 2026
d6fa5ae
feat(admin): implemented webhooks and outbound event system
AmanKrSahu Sep 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 16 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,10 +158,10 @@ The collection is structured logically into workflow folders matching realistic
2. `02. Authentication & Account Lifecycle` (Register, Verification, Login, Token Rotation, Logout, Lockouts, Forgot/Reset/Change Password)
3. `03. Passwordless (Magic Link)` (Request Magic Link, Verify Magic Link Token)
4. `04. Multi-Factor Authentication (MFA)` (TOTP Setup, Verify Setup, Login Challenge, Backup Code Recovery, Revoke MFA)
5. `05. Social Authentication (OAuth 2.0)` (Google OAuth Redirect & Callback Handling)
6. `06. User Profile Management` (Get Authenticated User Profile)
7. `07. Session Management` (List Active Sessions Paginated, Session Details, Revoke Session by ID, Revoke All Other Sessions)
8. `08. Admin Controls & Role Management` (Role Promotion, Query System Users, Delete User, Manage Target User Sessions, Register OIDC Clients)
5. `05. OAuth 2.0 (Google)` (Google OAuth Redirect, Google OAuth Callback)
6. `06. User & Session Management` (Profile Info, Paginated Session Listing, Revoke Single Session, Revoke All Other Sessions)
7. `07. Admin Operations` (Promote User, Delete Account, Revoke Target Sessions, Register OIDC Client, Paginated User Queries, Paginated Audit Logs, Audit Log Details)
8. `08. Webhook & Event System` (Create Webhook Subscription, List Subscriptions, Get Details, Update Config, Rotate Signing Secret, Trigger Test Delivery, List Deliveries, Get Delivery Details)
9. `09. OpenID Connect (OIDC 1.0) Provider Protocols` (Discovery, JWKS Keys, Authorization Code PKCE, Token Exchange, UserInfo, Introspection, Revocation)
10. `10. OIDC Custom Interaction Flows` (Interaction Prompt Details, Session Bridge Check, Submit Login/MFA/Consent, Abort Interaction)

Expand Down Expand Up @@ -221,17 +221,18 @@ AuthKit functions as a centralized IdP, supporting dynamic client registration a

## 7. API Inventory & Endpoint Specifications

| Domain | Functional Scope | Protocol / Logic | Details |
| :----------------- | :-------------------------- | :--------------------- | :------------------------------------------------ |
| **Identity (IdP)** | Auth, Token, JWKS, UserInfo | OIDC 1.0 / OAuth 2.0 | Centralized SSO & Third-party provisioning |
| **Auth** | Registration, Login, Logout | Password-based Auth | Secure credential handling & session initiation |
| **MFA** | TOTP Setup & Verification | RFC 6238 (speakeasy) | Multi-factor secondary verification layer |
| **OAuth** | Google Social Integration | OAuth 2.0 Protocol | Third-party identity federation |
| **Magic Link** | Passwordless Auth | Token-based / SMTP | Email-verified session provisioning |
| **User/Session** | Profile & Active State Mgmt | REST / Redis-backed | Real-time session tracking & profile modification |
| **Admin** | Moderation & Client Ops | Restricted REST / RBAC | User lifecycle moderation & Client Registration |
| **System** | Health & Dependency Checks | Heartbeat Logic | Multi-component dependency status monitoring |
| **Metadata** | Discovery, Key Exposition | RFC 8414 | Automated client configuration (Well-known) |
| Domain | Functional Scope | Protocol / Logic | Details |
| :----------------- | :-------------------------- | :--------------------- | :---------------------------------------------------- |
| **Identity (IdP)** | Auth, Token, JWKS, UserInfo | OIDC 1.0 / OAuth 2.0 | Centralized SSO & Third-party provisioning |
| **Auth** | Registration, Login, Logout | Password-based Auth | Secure credential handling & session initiation |
| **MFA** | TOTP Setup & Verification | RFC 6238 (speakeasy) | Multi-factor secondary verification layer |
| **OAuth** | Google Social Integration | OAuth 2.0 Protocol | Third-party identity federation |
| **Magic Link** | Passwordless Auth | Token-based / SMTP | Email-verified session provisioning |
| **User/Session** | Profile & Active State Mgmt | REST / Redis-backed | Real-time session tracking & profile modification |
| **Admin** | Moderation & Client Ops | Restricted REST / RBAC | User lifecycle moderation & Client Registration |
| **Audit Logs** | Compliance & Observability | SOC2 / NIST SP 800-92 | Append-only security audit trail & filterable queries |
| **System** | Health & Dependency Checks | Heartbeat Logic | Multi-component dependency status monitoring |
| **Metadata** | Discovery, Key Exposition | RFC 8414 | Automated client configuration (Well-known) |

Comprehensive specifications including request/response schemas are accessible via the Swagger portal (in Dev/Staging) or via the [**Postman Collection**](./docs/api-specs/AuthKit.postman_collection.json).

Expand Down
177 changes: 177 additions & 0 deletions docs/api-specs/AuthKit.postman_collection.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -746,6 +746,183 @@
},
"description": "Registers a new OIDC client application and generates credentials."
}
},
{
"name": "List Audit Logs (Paginated & Filtered)",
"request": {
"method": "GET",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/audit-logs?limit=100",
"host": ["{{baseUrl}}"],
"path": ["admin", "audit-logs"],
"query": [{ "key": "limit", "value": "100" }]
},
"description": "Queries security audit logs with cursor-based pagination and filtering by action, status, userId, or date ranges."
}
},
{
"name": "Get Audit Log Details by ID",
"request": {
"method": "GET",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/audit-logs/:id",
"host": ["{{baseUrl}}"],
"path": ["admin", "audit-logs", ":id"],
"variable": [{ "key": "id", "value": "audit_log_id_here" }]
},
"description": "Retrieves audit log details by log ID with sensitive metadata fields redacted."
}
},
{
"name": "Webhooks & Outbound Events",
"description": "Webhook subscription management, HMAC secret rotation, test event delivery, and delivery audit history.",
"item": [
{
"name": "Create Webhook Subscription",
"request": {
"method": "POST",
"header": [
{ "key": "Content-Type", "value": "application/json" },
{ "key": "Authorization", "value": "Bearer {{accessToken}}" }
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Production Audit Webhook\",\n \"url\": \"https://example.com/webhooks\",\n \"description\": \"Subscribes to user lifecycle and security events\",\n \"events\": [\"user.created\", \"user.login\", \"user.deleted\"]\n}"
},
"url": {
"raw": "{{baseUrl}}/admin/webhooks",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks"]
},
"description": "Creates a new webhook subscription and generates a cryptographically secure signing secret."
}
},
{
"name": "List Webhook Subscriptions",
"request": {
"method": "GET",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/webhooks?limit=10",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks"],
"query": [{ "key": "limit", "value": "10" }]
},
"description": "Retrieves paginated webhook subscriptions."
}
},
{
"name": "Get Webhook Subscription Details",
"request": {
"method": "GET",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/webhooks/:id",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks", ":id"],
"variable": [{ "key": "id", "value": "subscription_id_here" }]
},
"description": "Retrieves details of a specific webhook subscription."
}
},
{
"name": "Update Webhook Subscription",
"request": {
"method": "PATCH",
"header": [
{ "key": "Content-Type", "value": "application/json" },
{ "key": "Authorization", "value": "Bearer {{accessToken}}" }
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Updated Webhook Name\",\n \"events\": [\"*\"]\n}"
},
"url": {
"raw": "{{baseUrl}}/admin/webhooks/:id",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks", ":id"],
"variable": [{ "key": "id", "value": "subscription_id_here" }]
},
"description": "Updates webhook subscription configuration, URL, events, or status."
}
},
{
"name": "Rotate Webhook Signing Secret",
"request": {
"method": "POST",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/webhooks/:id/rotate-secret",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks", ":id", "rotate-secret"],
"variable": [{ "key": "id", "value": "subscription_id_here" }]
},
"description": "Rotates signing secret for a webhook subscription with a 24-hour dual-signature grace window."
}
},
{
"name": "Dispatch Test Webhook Event",
"request": {
"method": "POST",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/webhooks/:id/test",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks", ":id", "test"],
"variable": [{ "key": "id", "value": "subscription_id_here" }]
},
"description": "Triggers a test webhook event delivery attempt to verify receiver endpoint health."
}
},
{
"name": "List Webhook Delivery History",
"request": {
"method": "GET",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/webhooks/:id/deliveries?limit=10",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks", ":id", "deliveries"],
"variable": [{ "key": "id", "value": "subscription_id_here" }],
"query": [{ "key": "limit", "value": "10" }]
},
"description": "Retrieves paginated delivery attempt history for a webhook subscription."
}
},
{
"name": "Get Webhook Delivery Details",
"request": {
"method": "GET",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/webhooks/:id/deliveries/:deliveryId",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks", ":id", "deliveries", ":deliveryId"],
"variable": [
{ "key": "id", "value": "subscription_id_here" },
{ "key": "deliveryId", "value": "delivery_id_here" }
]
},
"description": "Retrieves details of a specific webhook delivery attempt."
}
},
{
"name": "Delete Webhook Subscription",
"request": {
"method": "DELETE",
"header": [{ "key": "Authorization", "value": "Bearer {{accessToken}}" }],
"url": {
"raw": "{{baseUrl}}/admin/webhooks/:id",
"host": ["{{baseUrl}}"],
"path": ["admin", "webhooks", ":id"],
"variable": [{ "key": "id", "value": "subscription_id_here" }]
},
"description": "Deletes a webhook subscription and its associated delivery records."
}
}
]
}
]
},
Expand Down
Loading
Loading