Repository navigation
feat(c4): pair codes + capability tokens #6
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.
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| -- 0002_c4_capabilities.sql | ||
| -- C4 schema delta. 0001 is immutable. | ||
| -- Digest-only pair codes and capabilities. Bind bird_id + flock_id. | ||
| -- Explicit scopes already exist on computer_capabilities from 0001. | ||
|
|
||
| ALTER TABLE computer_pair_codes | ||
| ADD COLUMN IF NOT EXISTS bird_id TEXT NOT NULL DEFAULT ''; | ||
|
|
||
| ALTER TABLE computer_pair_codes | ||
| ADD COLUMN IF NOT EXISTS flock_id TEXT NOT NULL DEFAULT ''; | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
|
|
||
| CREATE INDEX IF NOT EXISTS idx_pair_codes_digest ON computer_pair_codes (code_digest); | ||
| CREATE INDEX IF NOT EXISTS idx_pair_codes_identity ON computer_pair_codes (bird_id, flock_id); | ||
|
|
||
| ALTER TABLE computer_capabilities | ||
| ADD COLUMN IF NOT EXISTS flock_id TEXT NOT NULL DEFAULT ''; | ||
|
|
||
| -- 0001 created a non-unique digest index. Replace it in place (same name) | ||
| -- so fresh and already-applied databases end with one unique index. | ||
| DROP INDEX IF EXISTS idx_capabilities_token_digest; | ||
| CREATE UNIQUE INDEX IF NOT EXISTS idx_capabilities_token_digest | ||
| ON computer_capabilities (token_digest); | ||
|
|
||
| CREATE INDEX IF NOT EXISTS idx_capabilities_identity | ||
| ON computer_capabilities (computer_id, bird_id, flock_id); | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,41 @@ | ||
| /** | ||
| * Capability token helpers. | ||
| * Tokens are 256-bit random values; only digests are stored. | ||
| * Scoped to one computer_id + bird_id. | ||
| * Bound to exact computer_id + bird_id + flock_id. Scoped, expiring, revocable. | ||
| * | ||
| * Shared account / MCP authentication is never sufficient on its own. | ||
| */ | ||
|
|
||
| import { createHash, randomBytes } from "node:crypto"; | ||
| import { CapabilityRevoked } from "./errors.js"; | ||
| import { randomBytes } from "node:crypto"; | ||
| import { | ||
| CapabilityExpired, | ||
| CapabilityInvalid, | ||
| CapabilityMissing, | ||
| CapabilityRevoked, | ||
| CrossNodeDenied, | ||
| InsufficientScope, | ||
| InvalidScope, | ||
| } from "./errors.js"; | ||
| import { digestEquals, sha256Hex } from "./digest.js"; | ||
| import type { | ||
| CapabilityScope, | ||
| ComputerCapability, | ||
| ComputerOperationAuth, | ||
| SharedAccountAuth, | ||
| } from "./types.js"; | ||
| import { CAPABILITY_SCOPES } from "./types.js"; | ||
|
|
||
| const DEFAULT_CAPABILITY_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days | ||
| export const CAPABILITY_SECRET_BYTES = 32; // 256-bit | ||
| export const DEFAULT_CAPABILITY_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days | ||
|
|
||
| export const DEFAULT_PAIR_SCOPES: readonly CapabilityScope[] = [ | ||
| "status", | ||
| "exec", | ||
| "fs", | ||
| "observe", | ||
| "act", | ||
| "lifecycle", | ||
| ]; | ||
|
|
||
| export interface CapabilityMaterial { | ||
| /** Opaque token returned once to the Bot — never stored in plaintext */ | ||
|
|
@@ -18,11 +46,12 @@ export interface CapabilityMaterial { | |
| expiresAt: Date; | ||
| } | ||
|
|
||
| /** Issue a new capability token + its digest. */ | ||
| /** Mint a 256-bit capability secret + its digest. Never persist `token`. */ | ||
| export function issueCapability( | ||
| ttlMs: number = DEFAULT_CAPABILITY_TTL_MS, | ||
| ): CapabilityMaterial { | ||
| const token = randomBytes(32).toString("base64url"); | ||
| const raw = randomBytes(CAPABILITY_SECRET_BYTES); | ||
| const token = raw.toString("base64url"); | ||
| const digest = hashToken(token); | ||
| const issuedAt = new Date(); | ||
| const expiresAt = new Date(issuedAt.getTime() + ttlMs); | ||
|
|
@@ -31,45 +60,129 @@ export function issueCapability( | |
|
|
||
| /** SHA-256 hex digest of a capability token. */ | ||
| export function hashToken(token: string): string { | ||
| return createHash("sha256").update(token, "utf8").digest("hex"); | ||
| return sha256Hex(token); | ||
| } | ||
|
|
||
| export function parseScopes(scopes: readonly string[]): CapabilityScope[] { | ||
| const allowed = new Set<string>(CAPABILITY_SCOPES); | ||
| const out: CapabilityScope[] = []; | ||
| for (const scope of scopes) { | ||
| if (!allowed.has(scope)) { | ||
| throw new InvalidScope(scope); | ||
| } | ||
| const typed = scope as CapabilityScope; | ||
| if (!out.includes(typed)) out.push(typed); | ||
| } | ||
| return out; | ||
| } | ||
|
|
||
| export function copyScopes(scopes: readonly CapabilityScope[]): CapabilityScope[] { | ||
| return [...scopes]; | ||
| } | ||
|
|
||
| export function hasScope( | ||
| scopes: readonly string[], | ||
| required: CapabilityScope, | ||
| ): boolean { | ||
| return scopes.includes(required); | ||
| } | ||
|
|
||
| export interface CapabilityRecord { | ||
| capabilityId: string; | ||
| digest: string; | ||
| computerId: string; | ||
| birdId: string; | ||
| scopes: string[]; | ||
| flockId: string; | ||
| scopes: readonly string[]; | ||
| issuedAt: Date; | ||
| expiresAt: Date; | ||
| revokedAt: Date | null; | ||
| lastUsedAt: Date | null; | ||
| } | ||
|
|
||
| export interface CapabilityExpectation { | ||
| computerId: string; | ||
| birdId: string; | ||
| flockId: string; | ||
| scope?: CapabilityScope; | ||
| } | ||
|
Comment on lines
+103
to
+108
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win Make the identity binding mandatory in Every field is optional. A caller that calls
Require the binding fields and keep only 🔒️ Proposed fix to make binding mandatory export interface CapabilityExpectation {
- computerId?: string;
- birdId?: string;
- flockId?: string;
+ computerId: string;
+ birdId: string;
+ flockId: string;
scope?: CapabilityScope;
}Then make the parameter required and simplify the checks: export function isCapabilityValid(
presentedToken: string,
record: CapabilityRecord,
- expected?: CapabilityExpectation,
+ expected: CapabilityExpectation,
): void {- if (expected?.computerId !== undefined && record.computerId !== expected.computerId) {
+ if (record.computerId !== expected.computerId) {
throw new CrossNodeDenied(record.computerId, expected.computerId);
}
- if (expected?.birdId !== undefined && record.birdId !== expected.birdId) {
- throw new CrossNodeDenied(record.computerId, expected.computerId ?? record.computerId);
+ if (record.birdId !== expected.birdId) {
+ throw new CrossNodeDenied(record.computerId, expected.computerId);
}
- if (expected?.flockId !== undefined && record.flockId !== expected.flockId) {
- throw new CrossNodeDenied(record.computerId, expected.computerId ?? record.computerId);
+ if (record.flockId !== expected.flockId) {
+ throw new CrossNodeDenied(record.computerId, expected.computerId);
}
- if (expected?.scope !== undefined && !hasScope(record.scopes, expected.scope)) {
+ if (expected.scope !== undefined && !hasScope(record.scopes, expected.scope)) {
throw new InsufficientScope(expected.scope, record.scopes);
}The three call sites in 🤖 Prompt for AI Agents |
||
|
|
||
| export function toCapabilityRecord(cap: ComputerCapability): CapabilityRecord { | ||
| return { | ||
| capabilityId: cap.id, | ||
| digest: cap.tokenDigest, | ||
| computerId: cap.computerId, | ||
| birdId: cap.birdId, | ||
| flockId: cap.flockId, | ||
| scopes: copyScopes(cap.scopes), | ||
| issuedAt: cap.issuedAt, | ||
| expiresAt: cap.expiresAt, | ||
| revokedAt: cap.revokedAt, | ||
| lastUsedAt: cap.lastUsedAt, | ||
| }; | ||
| } | ||
|
|
||
| /** | ||
| * Validate a presented token against a stored capability record. | ||
| * Throws CapabilityRevoked on any failure. | ||
| * On success the caller should update lastUsedAt. | ||
| * Fail-closed with a specific error. Possession (digest) is checked before | ||
| * lifecycle state so callers without the token cannot probe revoked/expired. | ||
| * Binding (computer/bird/flock) is mandatory. Caller updates lastUsedAt on success. | ||
| */ | ||
| export function isCapabilityValid( | ||
| presentedToken: string, | ||
| record: CapabilityRecord, | ||
| expectedComputerId?: string, | ||
| expectedBirdId?: string, | ||
| expected: CapabilityExpectation, | ||
| ): void { | ||
| if (presentedToken.length === 0) { | ||
| throw new CapabilityMissing("missing capability"); | ||
| } | ||
| const presentedDigest = hashToken(presentedToken); | ||
| if (!digestEquals(presentedDigest, record.digest)) { | ||
| throw new CapabilityInvalid("mismatch"); | ||
| } | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| if (record.revokedAt !== null) { | ||
| throw new CapabilityRevoked(record.digest.slice(0, 8)); | ||
| throw new CapabilityRevoked(record.capabilityId); | ||
| } | ||
| if (Date.now() > record.expiresAt.getTime()) { | ||
| throw new CapabilityRevoked("expired"); | ||
| throw new CapabilityExpired(record.capabilityId); | ||
| } | ||
| if (expectedComputerId && record.computerId !== expectedComputerId) { | ||
| throw new CapabilityRevoked("wrong computer"); | ||
| if (record.computerId !== expected.computerId) { | ||
| throw new CrossNodeDenied(record.computerId, expected.computerId); | ||
| } | ||
| if (expectedBirdId && record.birdId !== expectedBirdId) { | ||
| throw new CapabilityRevoked("wrong bird"); | ||
| if (record.birdId !== expected.birdId) { | ||
| throw new CrossNodeDenied(record.computerId, expected.computerId); | ||
| } | ||
| const presentedDigest = hashToken(presentedToken); | ||
| if (presentedDigest !== record.digest) { | ||
| throw new CapabilityRevoked("mismatch"); | ||
| if (record.flockId !== expected.flockId) { | ||
| throw new CrossNodeDenied(record.computerId, expected.computerId); | ||
| } | ||
| if (expected.scope !== undefined && !hasScope(record.scopes, expected.scope)) { | ||
| throw new InsufficientScope(expected.scope, record.scopes); | ||
| } | ||
| } | ||
|
|
||
| export function capabilityAuth(token: string): ComputerOperationAuth { | ||
| return { kind: "capability", token }; | ||
| } | ||
|
|
||
| export function sharedAccountAuth(accountId: string): SharedAccountAuth { | ||
| return { accountId }; | ||
| } | ||
|
|
||
| export function sharedOperationAuth(accountId: string): ComputerOperationAuth { | ||
| return { kind: "shared", accountId }; | ||
| } | ||
|
|
||
| export const NO_OPERATION_AUTH: ComputerOperationAuth = { kind: "none" }; | ||
|
|
||
| export function extractCapabilityToken(auth: ComputerOperationAuth): string { | ||
| if (auth.kind === "shared") { | ||
| throw new CapabilityMissing("shared MCP auth is not sufficient"); | ||
| } | ||
| if (auth.kind === "none") { | ||
| throw new CapabilityMissing("missing capability"); | ||
| } | ||
| if (auth.kind !== "capability" || auth.token.length === 0) { | ||
| throw new CapabilityMissing("missing capability"); | ||
| } | ||
| return auth.token; | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| /** | ||
| * Digest helpers. Pair codes and capability tokens are stored as SHA-256 hex | ||
| * only. Comparisons are constant-time. | ||
| */ | ||
|
|
||
| import { createHash, timingSafeEqual } from "node:crypto"; | ||
|
|
||
| export function sha256Hex(value: string): string { | ||
| return createHash("sha256").update(value, "utf8").digest("hex"); | ||
| } | ||
|
|
||
| /** Constant-time equality for equal-length digest strings. */ | ||
| export function digestEquals(left: string, right: string): boolean { | ||
| const a = Buffer.from(left, "utf8"); | ||
| const b = Buffer.from(right, "utf8"); | ||
| if (a.length !== b.length) { | ||
| return false; | ||
| } | ||
| return timingSafeEqual(a, b); | ||
| } |
Uh oh!
There was an error while loading. Please reload this page.