@tumbaland/backend-core 1.29.0 → 1.31.0

package/src/apiKeys/service.ts

@@ -0,0 +1,149 @@
+import { ApiKey, IApiKey } from './ApiKey';
+import {
+  decryptSecret,
+  displayPrefix,
+  encryptSecret,
+  generateKey,
+  parseKey,
+  secretMatches
+} from './crypto';
+import type { ApiKeyScope, ApiKeySummary, ApiKeyVerification } from './types';
+
+export interface CreateApiKeyInput {
+  userId: string;
+  userEmail: string;
+  userName: string;
+  name: string;
+  scopes: ApiKeyScope[];
+  /** null pins the key to the user's own non-group data */
+  groupId?: string | null;
+  expiresAt?: Date | null;
+}
+
+export interface CreatedApiKey {
+  summary: ApiKeySummary;
+  /** the full token — the only time it is returned without an explicit reveal */
+  token: string;
+}
+
+const toSummary = (key: IApiKey): ApiKeySummary => ({
+  id: String(key._id),
+  name: key.name,
+  prefix: displayPrefix(key.keyId),
+  scopes: key.scopes,
+  groupId: key.groupId ?? null,
+  createdAt: key.createdAt.toISOString(),
+  lastUsedAt: key.lastUsedAt?.toISOString() ?? null,
+  expiresAt: key.expiresAt?.toISOString() ?? null,
+  revokedAt: key.revokedAt?.toISOString() ?? null
+});
+
+export const createApiKey = async (input: CreateApiKeyInput): Promise<CreatedApiKey> => {
+  const { token, id, hash } = generateKey();
+  const sealed = encryptSecret(token);
+
+  const key = await ApiKey.create({
+    userId: input.userId,
+    userEmail: input.userEmail,
+    userName: input.userName,
+    name: input.name,
+    keyId: id,
+    hash,
+    sealedCiphertext: sealed.ciphertext,
+    sealedIv: sealed.iv,
+    sealedTag: sealed.tag,
+    scopes: input.scopes,
+    groupId: input.groupId ?? null,
+    expiresAt: input.expiresAt ?? undefined
+  });
+
+  return { summary: toSummary(key), token };
+};
+
+export const listApiKeys = async (userId: string): Promise<ApiKeySummary[]> => {
+  const keys = await ApiKey.find({ userId }).sort({ createdAt: -1 });
+  return keys.map(toSummary);
+};
+
+/**
+ * Read a key back in the clear.
+ *
+ * Scoped to the owner by query rather than by a check afterwards, so there is no
+ * path where a mismatched userId still reaches the decrypt. Revoked keys are
+ * still revealable — the user may need to see which key they just turned off.
+ */
+export const revealApiKey = async (userId: string, id: string): Promise<string | null> => {
+  const key = await ApiKey.findOne({ _id: id, userId });
+  if (!key) return null;
+
+  const token = decryptSecret({
+    ciphertext: key.sealedCiphertext,
+    iv: key.sealedIv,
+    tag: key.sealedTag
+  });
+
+  key.revealCount += 1;
+  key.lastRevealedAt = new Date();
+  await key.save();
+
+  return token;
+};
+
+/** Revoking is a tombstone, not a delete: the audit trail outlives the key. */
+export const revokeApiKey = async (userId: string, id: string): Promise<ApiKeySummary | null> => {
+  const key = await ApiKey.findOne({ _id: id, userId });
+  if (!key) return null;
+
+  if (!key.revokedAt) {
+    key.revokedAt = new Date();
+    await key.save();
+  }
+
+  return toSummary(key);
+};
+
+export const deleteApiKey = async (userId: string, id: string): Promise<boolean> => {
+  const { deletedCount } = await ApiKey.deleteOne({ _id: id, userId });
+  return deletedCount > 0;
+};
+
+/**
+ * Check a presented token.
+ *
+ * Every failure returns the same shape and the caller answers all of them with
+ * one message: distinguishing "no such key" from "wrong secret" to the client
+ * would confirm which half of a guess was right. The `rejection` field exists
+ * for the server's own logs.
+ *
+ * `lastUsedAt` is written on the side and never awaited — it is a convenience
+ * for the listing UI, and making every authenticated request wait on a write to
+ * maintain it would be a poor trade.
+ */
+export const verifyApiKey = async (token: unknown): Promise<ApiKeyVerification> => {
+  const parsed = parseKey(token);
+  if (!parsed) return { ok: false, rejection: 'malformed' };
+
+  const key = await ApiKey.findOne({ keyId: parsed.id });
+  if (!key) return { ok: false, rejection: 'unknown' };
+  if (key.revokedAt) return { ok: false, rejection: 'revoked' };
+  if (key.expiresAt && key.expiresAt.getTime() <= Date.now()) {
+    return { ok: false, rejection: 'expired' };
+  }
+  if (!secretMatches(parsed.secret, key.hash)) {
+    return { ok: false, rejection: 'bad-secret' };
+  }
+
+  void ApiKey.updateOne({ _id: key._id }, { $set: { lastUsedAt: new Date() } }).catch(() => {
+    // A missed usage timestamp must never fail an otherwise valid request.
+  });
+
+  return {
+    ok: true,
+    userId: key.userId,
+    userEmail: key.userEmail,
+    userName: key.userName,
+    keyId: String(key._id),
+    scopes: key.scopes,
+    groupId: key.groupId ?? null
+  };
+};

package/src/apiKeys/types.ts

@@ -0,0 +1,69 @@
+/**
+ * API keys let a non-browser client — an MCP server driving Claude or ChatGPT,
+ * a script, a cron job — act as a user without a Google sign-in flow.
+ *
+ * They are deliberately narrower than a session: a session is a person at a
+ * keyboard who can see what they are doing, while a key is handed to software
+ * that acts on its own. So a key carries explicit scopes, and it pins the tenant
+ * it writes to rather than choosing one per request the way the UI does.
+ */
+
+/** Everything a key may be granted. Read and write are separate on purpose. */
+export const API_KEY_SCOPES = [
+  'relationship:read',
+  'relationship:write',
+  'album:read',
+  'album:write',
+  'finance:read',
+  'finance:write'
+] as const;
+
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+
+export const isApiKeyScope = (value: unknown): value is ApiKeyScope =>
+  typeof value === 'string' && (API_KEY_SCOPES as readonly string[]).includes(value);
+
+/**
+ * The tenant a key acts in, fixed when the key is created.
+ *
+ * The web app picks this per request from a tenant selector, but an agent has no
+ * such UI and no way to know it guessed wrong — so the choice is made once, by a
+ * person, and the key cannot escape it. `groupId: null` means the user's own
+ * non-group data.
+ */
+export interface ApiKeyTenant {
+  groupId: string | null;
+}
+
+/** A key as the API hands it back — never including the secret. */
+export interface ApiKeySummary {
+  id: string;
+  name: string;
+  /** the public half, shown in listings so a key is identifiable at a glance */
+  prefix: string;
+  scopes: ApiKeyScope[];
+  groupId: string | null;
+  createdAt: string;
+  lastUsedAt: string | null;
+  expiresAt: string | null;
+  revokedAt: string | null;
+}
+
+/** Why a presented key was refused. Kept out of the HTTP response — see the middleware. */
+export type ApiKeyRejection =
+  | 'malformed'
+  | 'unknown'
+  | 'revoked'
+  | 'expired'
+  | 'bad-secret';
+
+export interface ApiKeyVerification {
+  ok: boolean;
+  rejection?: ApiKeyRejection;
+  userId?: string;
+  userEmail?: string;
+  userName?: string;
+  keyId?: string;
+  scopes?: ApiKeyScope[];
+  groupId?: string | null;
+}

package/src/index.ts

@@ -30,6 +30,9 @@ export * from './entitlements';
 // Group ownership (the quota subject for anything pooled)
 export * from './groups';
 
+// API keys (non-browser clients: MCP servers, scripts, agents)
+export * from './apiKeys';
+
 // Middleware
 export { authenticateToken, optionalAuth } from './middleware/authMiddleware';
 export {