@tumbaland/backend-core 1.29.0 → 1.31.0

package/dist/apiKeys/service.d.ts

@@ -0,0 +1,43 @@
+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;
+}
+export declare const createApiKey: (input: CreateApiKeyInput) => Promise<CreatedApiKey>;
+export declare const listApiKeys: (userId: string) => Promise<ApiKeySummary[]>;
+/**
+ * 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 declare const revealApiKey: (userId: string, id: string) => Promise<string | null>;
+/** Revoking is a tombstone, not a delete: the audit trail outlives the key. */
+export declare const revokeApiKey: (userId: string, id: string) => Promise<ApiKeySummary | null>;
+export declare const deleteApiKey: (userId: string, id: string) => Promise<boolean>;
+/**
+ * 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 declare const verifyApiKey: (token: unknown) => Promise<ApiKeyVerification>;
+//# sourceMappingURL=service.d.ts.map

package/dist/apiKeys/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/apiKeys/service.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE9E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;CACf;AAcD,eAAO,MAAM,YAAY,GAAU,OAAO,iBAAiB,KAAG,OAAO,CAAC,aAAa,CAoBlF,CAAC;AAEF,eAAO,MAAM,WAAW,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,aAAa,EAAE,CAGzE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAU,QAAQ,MAAM,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAepF,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,YAAY,GAAU,QAAQ,MAAM,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAU3F,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,QAAQ,MAAM,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,OAAO,CAG9E,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAU,OAAO,OAAO,KAAG,OAAO,CAAC,kBAAkB,CA2B7E,CAAC"}

package/dist/apiKeys/service.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyApiKey = exports.deleteApiKey = exports.revokeApiKey = exports.revealApiKey = exports.listApiKeys = exports.createApiKey = void 0;
+const ApiKey_1 = require("./ApiKey");
+const crypto_1 = require("./crypto");
+const toSummary = (key) => ({
+    id: String(key._id),
+    name: key.name,
+    prefix: (0, crypto_1.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
+});
+const createApiKey = async (input) => {
+    const { token, id, hash } = (0, crypto_1.generateKey)();
+    const sealed = (0, crypto_1.encryptSecret)(token);
+    const key = await ApiKey_1.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 };
+};
+exports.createApiKey = createApiKey;
+const listApiKeys = async (userId) => {
+    const keys = await ApiKey_1.ApiKey.find({ userId }).sort({ createdAt: -1 });
+    return keys.map(toSummary);
+};
+exports.listApiKeys = listApiKeys;
+/**
+ * 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.
+ */
+const revealApiKey = async (userId, id) => {
+    const key = await ApiKey_1.ApiKey.findOne({ _id: id, userId });
+    if (!key)
+        return null;
+    const token = (0, crypto_1.decryptSecret)({
+        ciphertext: key.sealedCiphertext,
+        iv: key.sealedIv,
+        tag: key.sealedTag
+    });
+    key.revealCount += 1;
+    key.lastRevealedAt = new Date();
+    await key.save();
+    return token;
+};
+exports.revealApiKey = revealApiKey;
+/** Revoking is a tombstone, not a delete: the audit trail outlives the key. */
+const revokeApiKey = async (userId, id) => {
+    const key = await ApiKey_1.ApiKey.findOne({ _id: id, userId });
+    if (!key)
+        return null;
+    if (!key.revokedAt) {
+        key.revokedAt = new Date();
+        await key.save();
+    }
+    return toSummary(key);
+};
+exports.revokeApiKey = revokeApiKey;
+const deleteApiKey = async (userId, id) => {
+    const { deletedCount } = await ApiKey_1.ApiKey.deleteOne({ _id: id, userId });
+    return deletedCount > 0;
+};
+exports.deleteApiKey = deleteApiKey;
+/**
+ * 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.
+ */
+const verifyApiKey = async (token) => {
+    const parsed = (0, crypto_1.parseKey)(token);
+    if (!parsed)
+        return { ok: false, rejection: 'malformed' };
+    const key = await ApiKey_1.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 (!(0, crypto_1.secretMatches)(parsed.secret, key.hash)) {
+        return { ok: false, rejection: 'bad-secret' };
+    }
+    void ApiKey_1.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
+    };
+};
+exports.verifyApiKey = verifyApiKey;
+//# sourceMappingURL=service.js.map

package/dist/apiKeys/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/apiKeys/service.ts"],"names":[],"mappings":"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"}

package/dist/apiKeys/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare const API_KEY_SCOPES: readonly ["relationship:read", "relationship:write", "album:read", "album:write", "finance:read", "finance:write"];
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+export declare const isApiKeyScope: (value: unknown) => value is ApiKeyScope;
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/apiKeys/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/apiKeys/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,cAAc,oHAOjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WAC4B,CAAC;AAErF;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,2FAA2F;AAC3F,MAAM,MAAM,eAAe,GACvB,WAAW,GACX,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB"}

package/dist/apiKeys/types.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isApiKeyScope = exports.API_KEY_SCOPES = void 0;
+/** Everything a key may be granted. Read and write are separate on purpose. */
+exports.API_KEY_SCOPES = [
+    'relationship:read',
+    'relationship:write',
+    'album:read',
+    'album:write',
+    'finance:read',
+    'finance:write'
+];
+const isApiKeyScope = (value) => typeof value === 'string' && exports.API_KEY_SCOPES.includes(value);
+exports.isApiKeyScope = isApiKeyScope;
+//# sourceMappingURL=types.js.map

package/dist/apiKeys/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/apiKeys/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,+EAA+E;AAClE,QAAA,cAAc,GAAG;IAC5B,mBAAmB;IACnB,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,eAAe;CACP,CAAC;AAIJ,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AADxE,QAAA,aAAa,iBAC2D"}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFound
 export type { PaymentRequiredDetails } from './errors/HttpError';
 export * from './entitlements';
 export * from './groups';
+export * from './apiKeys';
 export { authenticateToken, optionalAuth } from './middleware/authMiddleware';
 export { requireInternalServiceToken, internalServiceTokenBypass, allowUserOrInternalService, verifyInternalToken, INTERNAL_TOKEN_HEADER, SERVICE_ID_HEADER } from './middleware/internalServiceAuth';
 export { createCorsMiddleware } from './middleware/corsMiddleware';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC7K,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,cAAc,gBAAgB,CAAC;AAG/B,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG9E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACT,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,UAAU,EACV,aAAa,EACb,kBAAkB,EACnB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC7K,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,cAAc,gBAAgB,CAAC;AAG/B,cAAc,UAAU,CAAC;AAGzB,cAAc,WAAW,CAAC;AAG1B,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG9E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACT,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,UAAU,EACV,aAAa,EACb,kBAAkB,EACnB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -56,6 +56,8 @@ Object.defineProperty(exports, "PaymentRequiredError", { enumerable: true, get:
 __exportStar(require("./entitlements"), exports);
 // Group ownership (the quota subject for anything pooled)
 __exportStar(require("./groups"), exports);
+// API keys (non-browser clients: MCP servers, scripts, agents)
+__exportStar(require("./apiKeys"), exports);
 // Middleware
 var authMiddleware_1 = require("./middleware/authMiddleware");
 Object.defineProperty(exports, "authenticateToken", { enumerable: true, get: function () { return authMiddleware_1.authenticateToken; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,qFAAqF;;;;;;;;;;;;;;;;;;;;;AAErF,gBAAgB;AAChB,qDAAoD;AAA3C,8GAAA,aAAa,OAAA;AAEtB,2CAAkD;AAAzC,4GAAA,gBAAgB,OAAA;AAGzB,UAAU;AACV,2CAAqD;AAA5C,iHAAA,OAAO,OAAU;AAE1B,gBAAgB;AAChB,8DAAoF;AAA3E,+GAAA,WAAW,OAAA;AAAE,8GAAA,UAAU,OAAA;AAAE,kHAAA,cAAc,OAAA;AAChD,gEAA+D;AAAtD,sHAAA,iBAAiB,OAAA;AAG1B,WAAW;AACX,oDAAgE;AAAvD,uGAAA,SAAS,OAAA;AAAE,0GAAA,YAAY,OAAA;AAEhC,SAAS;AACT,oCAA0C;AAAjC,iGAAA,UAAU,OAAA;AAEnB,SAAS;AACT,gDAA6K;AAApK,sGAAA,SAAS,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAGhJ,wDAAwD;AACxD,iDAA+B;AAE/B,0DAA0D;AAC1D,2CAAyB;AAEzB,aAAa;AACb,8DAA8E;AAArE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AACxC,wEAO0C;AANxC,kIAAA,2BAA2B,OAAA;AAC3B,iIAAA,0BAA0B,OAAA;AAC1B,iIAAA,0BAA0B,OAAA;AAC1B,0HAAA,mBAAmB,OAAA;AACnB,4HAAA,qBAAqB,OAAA;AACrB,wHAAA,iBAAiB,OAAA;AAEnB,8DAAmE;AAA1D,sHAAA,oBAAoB,OAAA;AAC7B,0DAAyD;AAAhD,4GAAA,YAAY,OAAA;AACrB,4DAA0G;AAAjG,8GAAA,aAAa,OAAA;AAAE,yHAAA,wBAAwB,OAAA;AAAE,oHAAA,mBAAmB,OAAA;AACrE,kDAAmH;AAA1G,2GAAA,eAAe,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AACnF,kDAAiD;AAAxC,oGAAA,QAAQ,OAAA;AAKjB,QAAQ;AACR,mDAAmF;AAA1E,oHAAA,qBAAqB,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AACrD,6CAA6E;AAApE,6GAAA,iBAAiB,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,qGAAA,SAAS,OAAA;AAElD,2DAA8E;AAArE,mHAAA,gBAAgB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAE5C,UAAU;AACV,qCAQmB;AAPjB,4GAAA,iBAAiB,OAAA;AACjB,8GAAA,mBAAmB,OAAA;AACnB,4GAAA,iBAAiB,OAAA;AACjB,gHAAA,qBAAqB,OAAA;AACrB,+GAAA,oBAAoB,OAAA;AACpB,0GAAA,eAAe,OAAA;AACf,mGAAA,QAAQ,OAAA;AAGV,UAAU;AACV,qCAUmB;AATjB,qGAAA,UAAU,OAAA;AACV,oGAAA,SAAS,OAAA;AACT,oGAAA,SAAS,OAAA;AACT,4GAAA,iBAAiB,OAAA;AACjB,0GAAA,eAAe,OAAA;AACf,oGAAA,SAAS,OAAA;AACT,qGAAA,UAAU,OAAA;AACV,wGAAA,aAAa,OAAA;AACb,6GAAA,kBAAkB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,qFAAqF;;;;;;;;;;;;;;;;;;;;;AAErF,gBAAgB;AAChB,qDAAoD;AAA3C,8GAAA,aAAa,OAAA;AAEtB,2CAAkD;AAAzC,4GAAA,gBAAgB,OAAA;AAGzB,UAAU;AACV,2CAAqD;AAA5C,iHAAA,OAAO,OAAU;AAE1B,gBAAgB;AAChB,8DAAoF;AAA3E,+GAAA,WAAW,OAAA;AAAE,8GAAA,UAAU,OAAA;AAAE,kHAAA,cAAc,OAAA;AAChD,gEAA+D;AAAtD,sHAAA,iBAAiB,OAAA;AAG1B,WAAW;AACX,oDAAgE;AAAvD,uGAAA,SAAS,OAAA;AAAE,0GAAA,YAAY,OAAA;AAEhC,SAAS;AACT,oCAA0C;AAAjC,iGAAA,UAAU,OAAA;AAEnB,SAAS;AACT,gDAA6K;AAApK,sGAAA,SAAS,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAGhJ,wDAAwD;AACxD,iDAA+B;AAE/B,0DAA0D;AAC1D,2CAAyB;AAEzB,+DAA+D;AAC/D,4CAA0B;AAE1B,aAAa;AACb,8DAA8E;AAArE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AACxC,wEAO0C;AANxC,kIAAA,2BAA2B,OAAA;AAC3B,iIAAA,0BAA0B,OAAA;AAC1B,iIAAA,0BAA0B,OAAA;AAC1B,0HAAA,mBAAmB,OAAA;AACnB,4HAAA,qBAAqB,OAAA;AACrB,wHAAA,iBAAiB,OAAA;AAEnB,8DAAmE;AAA1D,sHAAA,oBAAoB,OAAA;AAC7B,0DAAyD;AAAhD,4GAAA,YAAY,OAAA;AACrB,4DAA0G;AAAjG,8GAAA,aAAa,OAAA;AAAE,yHAAA,wBAAwB,OAAA;AAAE,oHAAA,mBAAmB,OAAA;AACrE,kDAAmH;AAA1G,2GAAA,eAAe,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AACnF,kDAAiD;AAAxC,oGAAA,QAAQ,OAAA;AAKjB,QAAQ;AACR,mDAAmF;AAA1E,oHAAA,qBAAqB,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AACrD,6CAA6E;AAApE,6GAAA,iBAAiB,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,qGAAA,SAAS,OAAA;AAElD,2DAA8E;AAArE,mHAAA,gBAAgB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAE5C,UAAU;AACV,qCAQmB;AAPjB,4GAAA,iBAAiB,OAAA;AACjB,8GAAA,mBAAmB,OAAA;AACnB,4GAAA,iBAAiB,OAAA;AACjB,gHAAA,qBAAqB,OAAA;AACrB,+GAAA,oBAAoB,OAAA;AACpB,0GAAA,eAAe,OAAA;AACf,mGAAA,QAAQ,OAAA;AAGV,UAAU;AACV,qCAUmB;AATjB,qGAAA,UAAU,OAAA;AACV,oGAAA,SAAS,OAAA;AACT,oGAAA,SAAS,OAAA;AACT,4GAAA,iBAAiB,OAAA;AACjB,0GAAA,eAAe,OAAA;AACf,oGAAA,SAAS,OAAA;AACT,qGAAA,UAAU,OAAA;AACV,wGAAA,aAAa,OAAA;AACb,6GAAA,kBAAkB,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/apiKeys/ApiKey.ts

@@ -0,0 +1,75 @@
+import mongoose, { Document, Schema } from 'mongoose';
+import type { ApiKeyScope } from './types';
+
+/**
+ * One API key. Lives in backend-core rather than auth-service because both
+ * halves need it: auth-service issues and revokes keys, and every other service
+ * verifies them on the way in. All services share one database, so the model is
+ * shared rather than the lookup going over HTTP on every request.
+ */
+export interface IApiKey extends Document {
+  userId: string;
+  /**
+   * The owner's identity as it stood when the key was issued.
+   *
+   * Snapshotted so verifying a key stays a single indexed read. Every
+   * authenticated request would otherwise need a second query into the users
+   * collection to fill in a `UserPayload`, to serve fields almost no handler
+   * reads. The cost is that a later rename shows the old name on requests made
+   * with this key, which is a fair price and easy to reason about.
+   */
+  userEmail: string;
+  userName: string;
+  /** what the user called it — "Claude Code", "home assistant" */
+  name: string;
+  /** the public half of the token; unique, and what a presented key is looked up by */
+  keyId: string;
+  /** SHA-256 of the secret half — what verification actually compares against */
+  hash: string;
+  /** the whole token, encrypted, so the owner can read it back later */
+  sealedCiphertext: string;
+  sealedIv: string;
+  sealedTag: string;
+  scopes: ApiKeyScope[];
+  /** the tenant this key acts in; null means the user's own non-group data */
+  groupId: string | null;
+  lastUsedAt?: Date;
+  expiresAt?: Date;
+  revokedAt?: Date;
+  /** reveals are counted and timestamped — reading back a key is worth an audit trail */
+  revealCount: number;
+  lastRevealedAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const ApiKeySchema = new Schema<IApiKey>(
+  {
+    userId: { type: String, required: true, index: true },
+    userEmail: { type: String, required: true },
+    userName: { type: String, required: true, default: '' },
+    name: { type: String, required: true, trim: true, maxlength: 60 },
+    keyId: { type: String, required: true, unique: true, index: true },
+    hash: { type: String, required: true },
+    sealedCiphertext: { type: String, required: true },
+    sealedIv: { type: String, required: true },
+    sealedTag: { type: String, required: true },
+    scopes: { type: [String], default: [] },
+    // Explicitly nullable rather than optional: "personal scope" is a decision the
+    // creator made, and it must not be indistinguishable from a field nobody set.
+    groupId: { type: String, default: null },
+    lastUsedAt: { type: Date },
+    expiresAt: { type: Date },
+    revokedAt: { type: Date },
+    revealCount: { type: Number, default: 0 },
+    lastRevealedAt: { type: Date }
+  },
+  { timestamps: true, collection: 'api_keys' }
+);
+
+// Every listing is one user's keys, newest first.
+ApiKeySchema.index({ userId: 1, createdAt: -1 });
+
+export const ApiKey = mongoose.models.ApiKey
+  ? (mongoose.models.ApiKey as mongoose.Model<IApiKey>)
+  : mongoose.model<IApiKey>('ApiKey', ApiKeySchema);

package/src/apiKeys/crypto.test.ts

@@ -0,0 +1,161 @@
+const ORIGINAL_ENV = process.env;
+
+import {
+  generateKey,
+  parseKey,
+  looksLikeApiKey,
+  secretMatches,
+  encryptSecret,
+  decryptSecret,
+  displayPrefix,
+  sha256,
+  resetEncryptionKeyCache
+} from './crypto';
+
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV, API_KEY_ENCRYPTION_SECRET: 'test-encryption-secret' };
+  resetEncryptionKeyCache();
+});
+
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+  resetEncryptionKeyCache();
+});
+
+describe('generateKey', () => {
+  it('produces a prefixed token whose parts round-trip through parseKey', () => {
+    const { token, id, hash } = generateKey();
+    const parsed = parseKey(token);
+
+    expect(token.startsWith('tmb_live_')).toBe(true);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.id).toBe(id);
+    expect(sha256(parsed!.secret)).toBe(hash);
+  });
+
+  it('never repeats a key', () => {
+    const tokens = new Set(Array.from({ length: 50 }, () => generateKey().token));
+    expect(tokens.size).toBe(50);
+  });
+
+  it('does not store the secret in recoverable form in the hash', () => {
+    const { token, hash } = generateKey();
+    expect(hash).not.toContain(token);
+    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+describe('parseKey', () => {
+  it.each([
+    ['a non-string', 12345],
+    ['an empty string', ''],
+    ['a foreign prefix', 'sk_live_abcdef123456_secretsecretsecret'],
+    ['too few parts', 'tmb_live_abcdef123456'],
+    ['a missing secret', 'tmb_live_abcdef123456_'],
+    ['a non-hex id', 'tmb_live_ZZZZZZZZZZZZ_secretsecretsecret'],
+    ['a short id', 'tmb_live_abc_secretsecretsecret'],
+    ['a truncated secret', 'tmb_live_abcdef123456_short']
+  ])('rejects %s', (_label, token) => {
+    expect(parseKey(token)).toBeNull();
+  });
+
+  it('accepts a secret containing underscores, which base64url produces', () => {
+    // The alphabet is A-Za-z0-9-_, so roughly a third of real keys carry an
+    // underscore in the secret. Splitting the token on '_' rejected those.
+    expect(parseKey('tmb_live_abcdef123456_aa_bb_cc-dd_eeffgghhiijj')).toEqual({
+      id: 'abcdef123456',
+      secret: 'aa_bb_cc-dd_eeffgghhiijj'
+    });
+  });
+
+  it('round-trips every generated key, underscores and all', () => {
+    for (let i = 0; i < 200; i++) {
+      const { token, id } = generateKey();
+      expect(parseKey(token)?.id).toBe(id);
+    }
+  });
+
+  it('accepts a well-formed key', () => {
+    expect(parseKey('tmb_live_abcdef123456_aaaaaaaaaaaaaaaaaaaa')).toEqual({
+      id: 'abcdef123456',
+      secret: 'aaaaaaaaaaaaaaaaaaaa'
+    });
+  });
+});
+
+describe('looksLikeApiKey', () => {
+  it('separates our keys from JWTs so the caller can skip a pointless verify', () => {
+    expect(looksLikeApiKey(generateKey().token)).toBe(true);
+    expect(looksLikeApiKey('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.abc.def')).toBe(false);
+    expect(looksLikeApiKey(undefined)).toBe(false);
+  });
+});
+
+describe('secretMatches', () => {
+  it('accepts the right secret and rejects a wrong one', () => {
+    const { token, hash } = generateKey();
+    const { secret } = parseKey(token)!;
+
+    expect(secretMatches(secret, hash)).toBe(true);
+    expect(secretMatches(`${secret}x`, hash)).toBe(false);
+  });
+
+  it('returns false rather than throwing on a malformed stored hash', () => {
+    // timingSafeEqual throws on a length mismatch, which would turn a corrupt
+    // record into a 500 instead of a failed authentication.
+    expect(secretMatches('anything', 'not-a-sha256')).toBe(false);
+  });
+});
+
+describe('encryptSecret / decryptSecret', () => {
+  it('round-trips a token', () => {
+    const { token } = generateKey();
+    expect(decryptSecret(encryptSecret(token))).toBe(token);
+  });
+
+  it('produces different ciphertext each time, so equal keys are not detectable', () => {
+    const { token } = generateKey();
+    const a = encryptSecret(token);
+    const b = encryptSecret(token);
+
+    expect(a.ciphertext).not.toBe(b.ciphertext);
+    expect(a.iv).not.toBe(b.iv);
+  });
+
+  it('refuses to decrypt tampered ciphertext rather than returning rubbish', () => {
+    const sealed = encryptSecret(generateKey().token);
+    const flipped = Buffer.from(sealed.ciphertext, 'base64');
+    flipped[0] ^= 0xff;
+
+    expect(() =>
+      decryptSecret({ ...sealed, ciphertext: flipped.toString('base64') })
+    ).toThrow();
+  });
+
+  it('cannot be decrypted with a different encryption secret', () => {
+    const sealed = encryptSecret(generateKey().token);
+
+    process.env.API_KEY_ENCRYPTION_SECRET = 'a-completely-different-secret';
+    resetEncryptionKeyCache();
+
+    expect(() => decryptSecret(sealed)).toThrow();
+  });
+
+  it('requires the encryption secret to be configured at all', () => {
+    delete process.env.API_KEY_ENCRYPTION_SECRET;
+    resetEncryptionKeyCache();
+
+    expect(() => encryptSecret('tmb_live_x')).toThrow(/API_KEY_ENCRYPTION_SECRET/);
+  });
+});
+
+describe('displayPrefix', () => {
+  it('identifies a key without exposing enough to use it', () => {
+    const { token, id } = generateKey();
+    const prefix = displayPrefix(id);
+
+    expect(prefix).toBe(`tmb_live_${id}`);
+    expect(token.startsWith(prefix)).toBe(true);
+    expect(prefix.length).toBeLessThan(token.length);
+  });
+});