cred402/lib/gateway/api_keys.ts
caelum0x f1c6d5f26d feat(gateway): add multi-tenant organizations with self-service API keys
Backlog item 13: API keys had no tenant boundary — any valid admin key (or,
in dev, no key at all) could see or mutate every key, webhook, and resource
in the process, which isn't multi-tenant for real paying integrators.

Adds a real org layer: the platform operator onboards a new org once
(POST /v1/orgs, admin-scoped) and gets its first owner key back; from then
on the org is fully self-service through its OWN key — GET /v1/orgs/me,
POST /v1/orgs/keys (mint a sibling key for a teammate, capped to a subset of
the caller's own scopes, no self-escalation), DELETE /v1/orgs/keys/:id
(revoke, but only inside the caller's own org_id — a different org's valid
key gets a 404, not the target's real state). The platform admin key is
never touched again after the initial onboarding call.

Also fixes a related gap this surfaced: lib/gateway/index.ts's authenticate()
previously ignored any presented API key entirely when
CRED402_AUTH_REQUIRED=false (dev), skipping scope checks even for a valid
key. A valid presented key is now resolved onto AuthContext and still scope-
checked in dev; a missing key still never blocks, so the existing zero-key
console workflow is unaffected.

Frontend: new Orgs.tsx (operator onboarding + self-service panels), wired
into Developer.tsx; api.ts helpers for all five new routes.

Verified for real against a running dev server: onboarded two orgs, had one
self-mint a teammate key with no admin key involved, confirmed scope-
escalation is rejected (403), confirmed cross-tenant revoke is rejected
(404), and confirmed the admin-only org-detail route rejects a non-admin
org's own valid key (403) — this one actually leaked before the
authenticate() fix above, caught by running the flow, not by inspection.
tsc --noEmit + frontend vite build clean, 450/450 existing tests unchanged.
2026-10-24 00:30:40 +03:00

94 lines
3.3 KiB
TypeScript

import { randomBytes, createHash, timingSafeEqual } from "node:crypto";
/**
* API key management (p2 §7.1).
*
* Keys are shown to the caller exactly once at creation; only a SHA-256 hash is
* stored, so a leak of the key store does not reveal usable credentials.
* Verification is constant-time. Each key carries scopes that authorize specific
* route groups (read, write, admin).
*/
export type Scope = "read" | "write" | "admin";
export interface ApiKeyRecord {
id: string; // public key id (safe to log)
name: string;
hash: string; // sha256(secret) hex
scopes: Scope[];
created_at: number;
revoked_at?: number;
last_used_at?: number;
/** Which {@link Org} this key belongs to. Undefined for the platform bootstrap/admin key — it is orgless by design, not a tenant. */
org_id?: string;
/** Successful-auth count — the basis for per-org usage reporting (org usage = sum over its keys). */
request_count: number;
}
export interface IssuedKey {
id: string;
/** The full secret — returned ONCE, never stored or logged. */
secret: string;
scopes: Scope[];
org_id?: string;
}
function sha256(input: string): string {
return createHash("sha256").update(input).digest("hex");
}
export class ApiKeyStore {
private readonly keys = new Map<string, ApiKeyRecord>(); // by id
constructor(private readonly now: () => number = () => Date.now()) {}
/** Mint a new key. The secret is `c402_<id>_<random>`; only its hash is kept. */
issue(name: string, scopes: Scope[], orgId?: string): IssuedKey {
const id = "k_" + randomBytes(6).toString("hex");
const secretPart = randomBytes(24).toString("base64url");
const secret = `c402_${id}_${secretPart}`;
this.keys.set(id, { id, name, hash: sha256(secret), scopes, created_at: this.now(), org_id: orgId, request_count: 0 });
return { id, secret, scopes, org_id: orgId };
}
/** Verify a presented secret and return its record, or undefined if invalid. */
verify(secret: string | undefined): ApiKeyRecord | undefined {
if (!secret) return undefined;
const m = /^c402_(k_[0-9a-f]{12})_/.exec(secret);
if (!m) return undefined;
const record = this.keys.get(m[1]!);
if (!record || record.revoked_at) return undefined;
const presented = Buffer.from(sha256(secret));
const stored = Buffer.from(record.hash);
if (presented.length !== stored.length || !timingSafeEqual(presented, stored)) return undefined;
record.last_used_at = this.now();
record.request_count += 1;
return record;
}
revoke(id: string): boolean {
const record = this.keys.get(id);
if (!record || record.revoked_at) return false;
record.revoked_at = this.now();
return true;
}
/** Public metadata only — never includes the hash. */
list(): Array<Omit<ApiKeyRecord, "hash">> {
return [...this.keys.values()].map(({ hash: _hash, ...rest }) => rest);
}
/** Keys belonging to one org — the tenant-scoped view a non-admin org key is allowed to see. */
listByOrg(orgId: string): Array<Omit<ApiKeyRecord, "hash">> {
return this.list().filter((k) => k.org_id === orgId);
}
get(id: string): ApiKeyRecord | undefined {
return this.keys.get(id);
}
hasScope(record: ApiKeyRecord, scope: Scope): boolean {
return record.scopes.includes("admin") || record.scopes.includes(scope);
}
}