@alteran/astro 0.1.0

package/src/lib/commit-log-pruning.ts

@@ -0,0 +1,76 @@
+import type { Env } from '../env';
+import { drizzle } from 'drizzle-orm/d1';
+import { commit_log } from '../db/schema';
+import { lt, desc } from 'drizzle-orm';
+import { logger } from './logger';
+
+/**
+ * Prune old commits from the commit log to prevent unbounded growth.
+ * Keeps the most recent N commits (default: 10000).
+ *
+ * This is safe because:
+ * - The current repo state is preserved in the MST and record tables
+ * - Recent commits are kept for firehose subscribers
+ * - Very old commits are not needed for sync operations
+ *
+ * @param env - Worker environment
+ * @param keepCount - Number of recent commits to keep (default: 10000)
+ * @returns Number of commits pruned
+ */
+export async function pruneOldCommits(env: Env, keepCount: number = 10000): Promise<number> {
+  const db = drizzle(env.DB);
+
+  // Get the sequence number of the Nth most recent commit
+  const threshold = await db
+    .select({ seq: commit_log.seq })
+    .from(commit_log)
+    .orderBy(desc(commit_log.seq))
+    .limit(1)
+    .offset(keepCount)
+    .get();
+
+  if (!threshold) {
+    // Less than keepCount commits exist, nothing to prune
+    logger.debug('commit_log_pruning', { message: 'No commits to prune', totalCommits: keepCount });
+    return 0;
+  }
+
+  // Delete all commits older than the threshold
+  const result = await db
+    .delete(commit_log)
+    .where(lt(commit_log.seq, threshold.seq))
+    .run();
+
+  const pruned = result.meta.changes || 0;
+  logger.info('commit_log_pruning', {
+    message: 'Pruned old commits',
+    pruned,
+    threshold: threshold.seq,
+    kept: keepCount
+  });
+
+  return pruned;
+}
+
+/**
+ * Get commit log statistics
+ */
+export async function getCommitLogStats(env: Env): Promise<{
+  total: number;
+  oldest: number | null;
+  newest: number | null;
+}> {
+  const db = drizzle(env.DB);
+
+  const [oldest, newest, count] = await Promise.all([
+    db.select({ seq: commit_log.seq }).from(commit_log).orderBy(commit_log.seq).limit(1).get(),
+    db.select({ seq: commit_log.seq }).from(commit_log).orderBy(desc(commit_log.seq)).limit(1).get(),
+    db.select({ count: commit_log.seq }).from(commit_log).all(),
+  ]);
+
+  return {
+    total: count.length,
+    oldest: oldest?.seq ?? null,
+    newest: newest?.seq ?? null,
+  };
+}

package/src/lib/commit.ts

@@ -0,0 +1,162 @@
+import { CID } from 'multiformats/cid';
+import * as dagCbor from '@ipld/dag-cbor';
+import { sha256 } from 'multiformats/hashes/sha2';
+
+/**
+ * AT Protocol Commit Structure
+ *
+ * A commit represents a snapshot of the repository at a specific revision.
+ * It includes:
+ * - did: The DID of the repository owner
+ * - version: Protocol version (currently 3)
+ * - data: CID of the MST root
+ * - rev: Revision number (TID format)
+ * - prev: CID of the previous commit (null for first commit)
+ * - sig: Ed25519 signature over the commit data
+ */
+
+export interface CommitData {
+  did: string;
+  version: number;
+  data: CID; // MST root CID
+  rev: string; // TID format revision
+  prev: CID | null; // Previous commit CID
+}
+
+export interface SignedCommit extends CommitData {
+  sig: Uint8Array;
+}
+
+/**
+ * Create a commit object
+ */
+export function createCommit(
+  did: string,
+  mstRoot: CID,
+  rev: string,
+  prev: CID | null = null,
+): CommitData {
+  return {
+    did,
+    version: 3,
+    data: mstRoot,
+    rev,
+    prev,
+  };
+}
+
+/**
+ * Sign a commit with Ed25519 private key
+ */
+export async function signCommit(
+  commit: CommitData,
+  privateKeyBase64: string,
+): Promise<SignedCommit> {
+  // Encode commit to CBOR for signing
+  const commitBytes = dagCbor.encode(commit);
+
+  // Import private key (PKCS#8 base64)
+  const b64 = privateKeyBase64.replace(/\s+/g, '');
+  const bin = atob(b64);
+  const pkcs8 = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) pkcs8[i] = bin.charCodeAt(i);
+  const privateKey = await crypto.subtle.importKey(
+    'pkcs8',
+    pkcs8,
+    { name: 'Ed25519', namedCurve: 'Ed25519' } as any,
+    false,
+    ['sign']
+  );
+
+  // Sign the commit bytes
+  const signature = await crypto.subtle.sign('Ed25519', privateKey, new Uint8Array(commitBytes as unknown as Uint8Array));
+
+  return {
+    ...commit,
+    sig: new Uint8Array(signature),
+  };
+}
+
+/**
+ * Verify a signed commit
+ */
+export async function verifyCommit(
+  signedCommit: SignedCommit,
+  publicKeyBase64: string,
+): Promise<boolean> {
+  try {
+    // Extract commit data (without signature)
+    const { sig, ...commit } = signedCommit;
+    const commitBytes = dagCbor.encode(commit);
+
+    // Import public key (SPKI base64)
+    const b64 = publicKeyBase64.replace(/\s+/g, '');
+    const bin = atob(b64);
+    const spki = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) spki[i] = bin.charCodeAt(i);
+    const publicKey = await crypto.subtle.importKey(
+      'spki',
+      spki,
+      { name: 'Ed25519', namedCurve: 'Ed25519' } as any,
+      false,
+      ['verify']
+    );
+
+    // Verify signature
+    return await crypto.subtle.verify('Ed25519', publicKey, sig as any, new Uint8Array(commitBytes as unknown as Uint8Array));
+  } catch (error) {
+    console.error('Commit verification failed:', error);
+    return false;
+  }
+}
+
+/**
+ * Calculate CID for a signed commit
+ */
+export async function commitCid(signedCommit: SignedCommit): Promise<CID> {
+  const bytes = dagCbor.encode(signedCommit);
+  const hash = await sha256.digest(bytes);
+  return CID.create(1, dagCbor.code, hash);
+}
+
+/**
+ * Serialize signed commit to bytes
+ */
+export function serializeCommit(signedCommit: SignedCommit): Uint8Array {
+  return dagCbor.encode(signedCommit);
+}
+
+/**
+ * Deserialize commit from bytes
+ */
+export function deserializeCommit(bytes: Uint8Array): SignedCommit {
+  return dagCbor.decode(bytes) as SignedCommit;
+}
+
+/**
+ * Generate a TID (Timestamp Identifier) for use as revision
+ * TIDs are lexicographically sortable timestamps
+ */
+export function generateTid(): string {
+  const now = Date.now();
+  const timestamp = now * 1000; // microseconds
+
+  // Convert to base32 (simplified version)
+  const chars = '234567abcdefghijklmnopqrstuvwxyz';
+  let tid = '';
+  let remaining = timestamp;
+
+  for (let i = 0; i < 13; i++) {
+    tid = chars[remaining % 32] + tid;
+    remaining = Math.floor(remaining / 32);
+  }
+
+  return tid;
+}
+
+/**
+ * Validate TID format
+ */
+export function isValidTid(tid: string): boolean {
+  return /^[234567abcdefghijklmnopqrstuvwxyz]{13}$/.test(tid);
+}

package/src/lib/config.ts

@@ -0,0 +1,208 @@
+import type { Env } from '../env';
+import { logger } from './logger';
+
+/**
+ * Required environment variables/secrets
+ */
+const REQUIRED_SECRETS = [
+  'PDS_DID',
+  'PDS_HANDLE',
+  'USER_PASSWORD',
+  'ACCESS_TOKEN_SECRET',
+  'REFRESH_TOKEN_SECRET',
+] as const;
+
+/**
+ * Optional environment variables with defaults
+ */
+const OPTIONAL_VARS = {
+  PDS_ALLOWED_MIME: 'image/jpeg,image/png,image/webp,image/gif,image/avif',
+  PDS_MAX_BLOB_SIZE: '5242880', // 5MB
+  PDS_MAX_JSON_BYTES: '65536', // 64KB
+  PDS_RATE_LIMIT_PER_MIN: '60',
+  PDS_CORS_ORIGIN: '*',
+  PDS_SEQ_WINDOW: '512',
+  ENVIRONMENT: 'development',
+} as const;
+
+/**
+ * Configuration validation result
+ */
+export interface ConfigValidationResult {
+  valid: boolean;
+  missing: string[];
+  warnings: string[];
+  config: {
+    required: Record<string, string>;
+    optional: Record<string, string>;
+  };
+}
+
+/**
+ * Validate environment configuration on startup
+ * Checks for required secrets and logs configuration status
+ *
+ * @param env - Worker environment
+ * @returns Validation result with missing secrets and warnings
+ */
+export function validateConfig(env: Env): ConfigValidationResult {
+  const missing: string[] = [];
+  const warnings: string[] = [];
+  const required: Record<string, string> = {};
+  const optional: Record<string, string> = {};
+
+  // Check required secrets
+  for (const secret of REQUIRED_SECRETS) {
+    const value = env[secret];
+    if (!value || value === '') {
+      missing.push(secret);
+    } else {
+      required[secret] = '***'; // Mask secret values in logs
+    }
+  }
+
+  // Check optional vars and apply defaults
+  for (const [key, defaultValue] of Object.entries(OPTIONAL_VARS)) {
+    const value = env[key as keyof Env] as string | undefined;
+    optional[key] = value || defaultValue;
+  }
+
+  // Validate specific configurations
+
+  // CORS validation
+  const corsOrigin = optional.PDS_CORS_ORIGIN;
+  if (corsOrigin === '*' && optional.ENVIRONMENT === 'production') {
+    warnings.push('PDS_CORS_ORIGIN is set to wildcard (*) in production - this is insecure');
+  }
+
+  // DID format validation
+  const did = env.PDS_DID;
+  if (did && !did.startsWith('did:')) {
+    warnings.push(`PDS_DID should start with 'did:' (got: ${did})`);
+  }
+
+  // Handle format validation
+  const handle = env.PDS_HANDLE;
+  if (handle && handle.includes('://')) {
+    warnings.push(`PDS_HANDLE should not include protocol (got: ${handle})`);
+  }
+
+  // Numeric validation
+  const maxBlobSize = parseInt(optional.PDS_MAX_BLOB_SIZE);
+  if (isNaN(maxBlobSize) || maxBlobSize <= 0) {
+    warnings.push(`PDS_MAX_BLOB_SIZE must be a positive number (got: ${optional.PDS_MAX_BLOB_SIZE})`);
+  }
+
+  const maxJsonBytes = parseInt(optional.PDS_MAX_JSON_BYTES);
+  if (isNaN(maxJsonBytes) || maxJsonBytes <= 0) {
+    warnings.push(`PDS_MAX_JSON_BYTES must be a positive number (got: ${optional.PDS_MAX_JSON_BYTES})`);
+  }
+
+  const rateLimit = parseInt(optional.PDS_RATE_LIMIT_PER_MIN);
+  if (isNaN(rateLimit) || rateLimit <= 0) {
+    warnings.push(`PDS_RATE_LIMIT_PER_MIN must be a positive number (got: ${optional.PDS_RATE_LIMIT_PER_MIN})`);
+  }
+
+  // Check for signing key
+  if (!env.REPO_SIGNING_KEY) {
+    warnings.push('REPO_SIGNING_KEY is not set - repository commits will not be signed');
+  }
+
+  const valid = missing.length === 0;
+
+  return {
+    valid,
+    missing,
+    warnings,
+    config: {
+      required,
+      optional,
+    },
+  };
+}
+
+/**
+ * Log configuration validation results
+ *
+ * @param result - Validation result
+ */
+export function logConfigValidation(result: ConfigValidationResult): void {
+  if (result.valid) {
+    logger.info('config_validation', {
+      message: 'Configuration validated successfully',
+      environment: result.config.optional.ENVIRONMENT,
+      warnings: result.warnings.length,
+    });
+
+    if (result.warnings.length > 0) {
+      for (const warning of result.warnings) {
+        logger.warn('config_validation', { message: warning });
+      }
+    }
+  } else {
+    logger.error('config_validation', {
+      message: 'Configuration validation failed',
+      missing: result.missing,
+      warnings: result.warnings,
+    });
+  }
+}
+
+/**
+ * Validate configuration and fail fast if invalid
+ * Call this on worker startup to ensure proper configuration
+ *
+ * @param env - Worker environment
+ * @throws Error if configuration is invalid
+ */
+export function validateConfigOrThrow(env: Env): void {
+  const result = validateConfig(env);
+  logConfigValidation(result);
+
+  if (!result.valid) {
+    const error = new Error(
+      `Configuration validation failed. Missing required secrets: ${result.missing.join(', ')}`
+    );
+    logger.error('config_validation', {
+      message: 'Startup failed due to invalid configuration',
+      error: error.message,
+    });
+    throw error;
+  }
+}
+
+/**
+ * Get parsed configuration values with defaults applied
+ *
+ * @param env - Worker environment
+ * @returns Parsed configuration object
+ */
+export function getConfig(env: Env) {
+  const result = validateConfig(env);
+
+  return {
+    // Required
+    did: env.PDS_DID!,
+    handle: env.PDS_HANDLE!,
+    userPassword: env.USER_PASSWORD!,
+    accessTokenSecret: env.ACCESS_TOKEN_SECRET!,
+    refreshTokenSecret: env.REFRESH_TOKEN_SECRET!,
+
+    // Optional with defaults
+    allowedMime: result.config.optional.PDS_ALLOWED_MIME.split(','),
+    maxBlobSize: parseInt(result.config.optional.PDS_MAX_BLOB_SIZE),
+    maxJsonBytes: parseInt(result.config.optional.PDS_MAX_JSON_BYTES),
+    rateLimitPerMin: parseInt(result.config.optional.PDS_RATE_LIMIT_PER_MIN),
+    corsOrigin: result.config.optional.PDS_CORS_ORIGIN,
+    seqWindow: parseInt(result.config.optional.PDS_SEQ_WINDOW),
+    environment: result.config.optional.ENVIRONMENT,
+
+    // Optional
+    repoSigningKey: env.REPO_SIGNING_KEY,
+    hostname: env.PDS_HOSTNAME,
+    accessTtlSec: env.PDS_ACCESS_TTL_SEC ? parseInt(env.PDS_ACCESS_TTL_SEC) : 3600,
+    refreshTtlSec: env.PDS_REFRESH_TTL_SEC ? parseInt(env.PDS_REFRESH_TTL_SEC) : 2592000,
+  };
+}
+
+export type Config = ReturnType<typeof getConfig>;

package/src/lib/errors.ts

@@ -0,0 +1,142 @@
+/**
+ * XRPC Error Hierarchy
+ * Implements AT Protocol error codes and consistent error handling
+ */
+
+export class XRPCError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public status: number,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'XRPCError';
+  }
+
+  toJSON() {
+    return {
+      error: this.code,
+      message: this.message,
+      ...(this.details && { details: this.details }),
+    };
+  }
+
+  toResponse(requestId?: string): Response {
+    const headers = new Headers({
+      'Content-Type': 'application/json',
+    });
+
+    if (requestId) {
+      headers.set('X-Request-ID', requestId);
+    }
+
+    return new Response(JSON.stringify(this.toJSON()), {
+      status: this.status,
+      headers,
+    });
+  }
+}
+
+// 400 - Bad Request
+export class InvalidRequest extends XRPCError {
+  constructor(message: string = 'Invalid request parameters', details?: Record<string, unknown>) {
+    super('InvalidRequest', message, 400, details);
+    this.name = 'InvalidRequest';
+  }
+}
+
+// 401 - Unauthorized
+export class AuthRequired extends XRPCError {
+  constructor(message: string = 'Authentication required', details?: Record<string, unknown>) {
+    super('AuthRequired', message, 401, details);
+    this.name = 'AuthRequired';
+  }
+}
+
+export class InvalidToken extends XRPCError {
+  constructor(message: string = 'Invalid or expired token', details?: Record<string, unknown>) {
+    super('InvalidToken', message, 401, details);
+    this.name = 'InvalidToken';
+  }
+}
+
+// 403 - Forbidden
+export class Forbidden extends XRPCError {
+  constructor(message: string = 'Access forbidden', details?: Record<string, unknown>) {
+    super('Forbidden', message, 403, details);
+    this.name = 'Forbidden';
+  }
+}
+
+// 404 - Not Found
+export class NotFound extends XRPCError {
+  constructor(message: string = 'Resource not found', details?: Record<string, unknown>) {
+    super('NotFound', message, 404, details);
+    this.name = 'NotFound';
+  }
+}
+
+// 429 - Rate Limit
+export class RateLimitExceeded extends XRPCError {
+  constructor(message: string = 'Rate limit exceeded', details?: Record<string, unknown>) {
+    super('RateLimitExceeded', message, 429, details);
+    this.name = 'RateLimitExceeded';
+  }
+}
+
+// 500 - Internal Server Error
+export class InternalServerError extends XRPCError {
+  constructor(message: string = 'Internal server error', details?: Record<string, unknown>) {
+    super('InternalServerError', message, 500, details);
+    this.name = 'InternalServerError';
+  }
+}
+
+/**
+ * User-friendly error messages
+ * Maps technical errors to actionable guidance
+ */
+export const USER_FRIENDLY_MESSAGES: Record<string, string> = {
+  AuthRequired: 'Please log in to continue.',
+  InvalidToken: 'Your session has expired. Please log in again.',
+  InvalidRequest: 'The request contains invalid data. Please check your input.',
+  Forbidden: 'You do not have permission to perform this action.',
+  NotFound: 'The requested resource could not be found.',
+  RateLimitExceeded: 'Too many requests. Please try again later.',
+  InternalServerError: 'An unexpected error occurred. Please try again.',
+};
+
+/**
+ * Get user-friendly message for error code
+ */
+export function getUserFriendlyMessage(code: string): string {
+  return USER_FRIENDLY_MESSAGES[code] || 'An error occurred. Please try again.';
+}
+
+/**
+ * Categorize error by status code
+ */
+export function categorizeError(status: number): 'client' | 'server' {
+  return status >= 400 && status < 500 ? 'client' : 'server';
+}
+
+/**
+ * Convert any error to XRPCError
+ */
+export function toXRPCError(error: unknown): XRPCError {
+  if (error instanceof XRPCError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new InternalServerError(error.message, {
+      originalError: error.name,
+      stack: error.stack,
+    });
+  }
+
+  return new InternalServerError('Unknown error occurred', {
+    error: String(error),
+  });
+}