@tumbaland/backend-core 1.38.0 → 1.40.0

package/src/audit/service.ts

@@ -0,0 +1,95 @@
+import { AuditEvent, type IAuditEvent, type ToolCall } from './AuditEvent';
+import type { ActorKind } from './actor';
+
+export interface AuditQuery {
+  userId: string;
+  /** narrow to one actor — a key's id or an OAuth client id */
+  credentialId?: string;
+  actorKind?: ActorKind;
+  action?: IAuditEvent['action'];
+  resource?: string;
+  /** narrow to one area — 'relationship-service', 'album-service' */
+  service?: string;
+  from?: Date;
+  to?: Date;
+  limit?: number;
+  page?: number;
+}
+
+export interface AuditEntry {
+  id: string;
+  at: string;
+  service: string;
+  action: IAuditEvent['action'];
+  resource: string;
+  resourceId?: string;
+  actorKind: ActorKind;
+  actorLabel: string;
+  actorCredentialId?: string;
+  tenant: string;
+  changes?: Record<string, { from: unknown; to: unknown }>;
+  snapshot?: Record<string, unknown>;
+  count?: number;
+  /** present on 'call': which tool ran, how long it took, and what it cost */
+  tool?: ToolCall;
+}
+
+const toEntry = (event: IAuditEvent): AuditEntry => ({
+  id: String(event._id),
+  at: event.at.toISOString(),
+  service: event.service,
+  action: event.action,
+  resource: event.resource,
+  resourceId: event.resourceId,
+  actorKind: event.actorKind,
+  actorLabel: event.actorLabel,
+  actorCredentialId: event.actorCredentialId,
+  tenant: event.tenant,
+  changes: event.changes,
+  snapshot: event.snapshot,
+  count: event.count,
+  tool: event.tool
+});
+
+/**
+ * One account's trail, newest first.
+ *
+ * Always scoped to `userId` by the query rather than filtered afterwards, so
+ * there is no path where a wider read is one forgotten condition away. The trail
+ * carries old values of journal entries, which makes it as sensitive as the
+ * journal itself.
+ */
+export const listAuditEvents = async (
+  query: AuditQuery
+): Promise<{ events: AuditEntry[]; total: number; page: number; totalPages: number }> => {
+  const limit = Math.min(query.limit ?? 50, 200);
+  const page = Math.max(query.page ?? 1, 1);
+
+  const filter: Record<string, unknown> = { userId: query.userId };
+  if (query.credentialId) filter.actorCredentialId = query.credentialId;
+  if (query.actorKind) filter.actorKind = query.actorKind;
+  if (query.action) filter.action = query.action;
+  if (query.resource) filter.resource = query.resource;
+  if (query.service) filter.service = query.service;
+  if (query.from || query.to) {
+    const at: Record<string, Date> = {};
+    if (query.from) at.$gte = query.from;
+    if (query.to) at.$lte = query.to;
+    filter.at = at;
+  }
+
+  const [events, total] = await Promise.all([
+    AuditEvent.find(filter)
+      .sort({ at: -1 })
+      .skip((page - 1) * limit)
+      .limit(limit),
+    AuditEvent.countDocuments(filter)
+  ]);
+
+  return {
+    events: events.map(toEntry),
+    total,
+    page,
+    totalPages: Math.ceil(total / limit)
+  };
+};

package/src/index.ts

@@ -35,6 +35,7 @@ export * from './apiKeys';
 
 // OAuth 2.1 authorization server, for assistants connecting over MCP
 export * from './oauth';
+export * from './audit';
 
 // Middleware
 export { authenticateToken, optionalAuth } from './middleware/authMiddleware';

package/src/middleware/authMiddleware.test.ts

@@ -195,7 +195,9 @@ describe('OAuth access tokens are not sessions', () => {
       scopes: ['relationship:read'],
       tenants: [PERSONAL_TENANT],
       defaultTenant: PERSONAL_TENANT,
-      tenantNames: {}
+      tenantNames: {},
+      clientId: 'client-1',
+      clientName: 'Claude'
     }).accessToken;
 
   it('refuses one on a session-only route', () => {

package/src/oauth/models.ts

@@ -1,4 +1,5 @@
 import mongoose, { Document, Schema } from 'mongoose';
+import { auditPlugin } from '../audit/plugin';
 import { PERSONAL_TENANT, type Tenant } from '../apiKeys/types';
 
 /**
@@ -148,6 +149,16 @@ const RefreshTokenSchema = new Schema<IRefreshToken>(
 
 RefreshTokenSchema.index({ userId: 1, createdAt: -1 });
 
+/**
+ * A grant appearing and being revoked is the shape of "who connected Claude,
+ * and when did it stop" — the question the connections page answers for the
+ * present and this answers for the past.
+ *
+ * `tokenHash` is redacted: it is the only thing standing between a copy of this
+ * collection and a working refresh token.
+ */
+RefreshTokenSchema.plugin(auditPlugin, { resource: 'connection', redact: ['tokenHash'] });
+
 export const RefreshToken = mongoose.models.RefreshToken
   ? (mongoose.models.RefreshToken as mongoose.Model<IRefreshToken>)
   : mongoose.model<IRefreshToken>('RefreshToken', RefreshTokenSchema);

package/src/oauth/tokens.test.ts

@@ -18,6 +18,8 @@ const mint = (over: Partial<Parameters<typeof mintAccessToken>[0]> = {}) =>
     tenants: [PERSONAL_TENANT],
     defaultTenant: PERSONAL_TENANT,
     tenantNames: { [PERSONAL_TENANT]: 'My own data' },
+    clientId: 'client-1',
+    clientName: 'Claude',
     ...over
   });
 

package/src/oauth/tokens.ts

@@ -49,6 +49,17 @@ export interface AccessTokenClaims {
   tenantNames: Record<Tenant, string>;
   /** the single tenant an older token was pinned to; read by `readTenants` */
   groupId?: string | null;
+  /**
+   * Which app this token was issued to.
+   *
+   * `jti` identifies the token and rotates every hour, so it cannot stand in for
+   * the connection — an audit trail built on it would show a different actor
+   * each time the assistant refreshed. The client id is stable for the life of
+   * the grant, and the name is snapshotted alongside it for the same reason the
+   * tenant names are: nothing downstream can look it up.
+   */
+  clientId: string;
+  clientName: string;
   email: string;
   name: string;
   typ: typeof ACCESS_TOKEN_TYPE;
@@ -68,6 +79,8 @@ export interface MintAccessTokenInput {
   tenants: Tenant[];
   defaultTenant: Tenant;
   tenantNames: Record<Tenant, string>;
+  clientId: string;
+  clientName: string;
 }
 
 export interface MintedAccessToken {
@@ -88,6 +101,8 @@ export const mintAccessToken = (input: MintAccessTokenInput): MintedAccessToken
       tenants: input.tenants,
       defaultTenant: input.defaultTenant,
       tenantNames: input.tenantNames,
+      clientId: input.clientId,
+      clientName: input.clientName,
       email: input.email,
       name: input.name,
       typ: ACCESS_TOKEN_TYPE,
@@ -109,6 +124,8 @@ export interface AccessTokenVerification {
   scopes?: ApiKeyScope[];
   tenants?: ApiKeyTenant;
   tenantNames?: Record<Tenant, string>;
+  clientId?: string;
+  clientName?: string;
 }
 
 /**
@@ -144,7 +161,9 @@ export const verifyAccessToken = (
     name: claims.name ?? '',
     scopes: (claims.scope ?? '').split(' ').filter(isApiKeyScope),
     tenants: readTenants(claims),
-    tenantNames: claims.tenantNames ?? {}
+    tenantNames: claims.tenantNames ?? {},
+    clientId: claims.clientId,
+    clientName: claims.clientName
   };
 };