@alteran/astro 0.1.0

package/src/lib/firehose/frames.ts

@@ -0,0 +1,229 @@
+import * as dagCbor from '@ipld/dag-cbor';
+import * as uint8arrays from 'uint8arrays';
+import { CID } from 'multiformats/cid';
+
+/**
+ * Frame types for AT Protocol firehose
+ */
+export enum FrameType {
+  Message = 1,
+  Error = -1,
+}
+
+/**
+ * Frame header structure
+ */
+export interface FrameHeader {
+  op: FrameType;
+  t?: string; // Message type discriminator
+}
+
+/**
+ * Error frame body
+ */
+export interface ErrorFrameBody {
+  error: string;
+  message?: string;
+}
+
+/**
+ * Base frame class
+ */
+export abstract class Frame {
+  abstract header: FrameHeader;
+  abstract body: unknown;
+
+  get op(): FrameType {
+    return this.header.op;
+  }
+
+  /**
+   * Encode frame to bytes (header + body as CBOR)
+   */
+  toBytes(): Uint8Array {
+    const headerBytes = dagCbor.encode(this.header);
+    const bodyBytes = dagCbor.encode(this.body);
+    return uint8arrays.concat([headerBytes, bodyBytes]);
+  }
+
+  /**
+   * Encode with 4-byte big-endian length prefix (payload = header||body encoded as dag-cbor)
+   */
+  toFramedBytes(): Uint8Array {
+    const payload = this.toBytes();
+    const prefix = new Uint8Array(4);
+    const len = payload.byteLength >>> 0;
+    prefix[0] = (len >>> 24) & 0xff;
+    prefix[1] = (len >>> 16) & 0xff;
+    prefix[2] = (len >>> 8) & 0xff;
+    prefix[3] = len & 0xff;
+    return uint8arrays.concat([prefix, payload]);
+  }
+
+  isMessage(): this is MessageFrame {
+    return this.op === FrameType.Message;
+  }
+
+  isError(): this is ErrorFrame {
+    return this.op === FrameType.Error;
+  }
+}
+
+/**
+ * Message frame for firehose events
+ */
+export class MessageFrame<T = unknown> extends Frame {
+  header: FrameHeader;
+  body: T;
+
+  constructor(body: T, type?: string) {
+    super();
+    this.header = type ? { op: FrameType.Message, t: type } : { op: FrameType.Message };
+    this.body = body;
+  }
+
+  get type(): string | undefined {
+    return this.header.t;
+  }
+}
+
+/**
+ * Error frame
+ */
+export class ErrorFrame extends Frame {
+  header: FrameHeader;
+  body: ErrorFrameBody;
+
+  constructor(error: string, message?: string) {
+    super();
+    this.header = { op: FrameType.Error };
+    this.body = { error, message };
+  }
+
+  get code(): string {
+    return this.body.error;
+  }
+
+  get message(): string | undefined {
+    return this.body.message;
+  }
+}
+
+/**
+ * Firehose message types
+ */
+
+export interface InfoMessage {
+  name: string;
+  message?: string;
+}
+
+export interface RepoOp {
+  action: 'create' | 'update' | 'delete';
+  path: string;
+  cid: CID | null;
+  prev?: CID;
+}
+
+export interface CommitMessage {
+  seq: number;
+  rebase: boolean;
+  tooBig: boolean;
+  repo: string; // DID
+  commit: CID;
+  prev: CID | null;
+  rev: string; // TID
+  since: string | null; // Previous TID
+  blocks: Uint8Array; // CAR bytes
+  ops: RepoOp[];
+  blobs: CID[];
+  time: string; // ISO 8601
+  prevData?: CID; // Previous MST root
+}
+
+export interface IdentityMessage {
+  seq: number;
+  did: string;
+  time: string;
+  handle?: string;
+}
+
+export interface AccountMessage {
+  seq: number;
+  did: string;
+  time: string;
+  active: boolean;
+  status?: string;
+}
+
+export interface SyncMessage {
+  seq: number;
+  did: string;
+  time: string;
+  active: boolean;
+  status?: string;
+}
+
+/**
+ * Create an #info frame
+ */
+export function createInfoFrame(name: string, message?: string): MessageFrame<InfoMessage> {
+  return new MessageFrame({ name, message }, '#info');
+}
+
+/**
+ * Create a #commit frame
+ */
+export function createCommitFrame(data: CommitMessage): MessageFrame<CommitMessage> {
+  return new MessageFrame(data, '#commit');
+}
+
+/**
+ * Create an #identity frame
+ */
+export function createIdentityFrame(data: IdentityMessage): MessageFrame<IdentityMessage> {
+  return new MessageFrame(data, '#identity');
+}
+
+/**
+ * Create an #account frame
+ */
+export function createAccountFrame(data: AccountMessage): MessageFrame<AccountMessage> {
+  return new MessageFrame(data, '#account');
+}
+
+/**
+ * Create a #sync frame (alias/compat for account-status changes)
+ */
+export function createSyncFrame(data: SyncMessage): MessageFrame<SyncMessage> {
+  return new MessageFrame(data, '#sync');
+}
+
+/**
+ * Create an error frame
+ */
+export function createErrorFrame(error: string, message?: string): ErrorFrame {
+  return new ErrorFrame(error, message);
+}
+
+// Binary encoders (with 4-byte length prefix)
+export function encodeInfoFrame(name: string, message?: string): Uint8Array {
+  return createInfoFrame(name, message).toFramedBytes();
+}
+
+export function encodeCommitFrame(data: CommitMessage): Uint8Array {
+  return createCommitFrame(data).toFramedBytes();
+}
+
+export function encodeIdentityFrame(data: IdentityMessage): Uint8Array {
+  return createIdentityFrame(data).toFramedBytes();
+}
+
+export function encodeAccountFrame(data: AccountMessage): Uint8Array {
+  return createAccountFrame(data).toFramedBytes();
+}
+
+// Alias for TODO nomenclature (#sync)
+export function encodeSyncFrame(data: SyncMessage): Uint8Array {
+  return createSyncFrame(data).toFramedBytes();
+}

package/src/lib/firehose/parse.ts

@@ -0,0 +1,82 @@
+import * as dagCbor from '@ipld/dag-cbor';
+
+function readU32BE(buf: Uint8Array, off = 0): number {
+  return ((buf[off] << 24) | (buf[off + 1] << 16) | (buf[off + 2] << 8) | buf[off + 3]) >>> 0;
+}
+
+function readVarUint(buf: Uint8Array, off: number, addl: number): { value: number; off: number } {
+  if (addl < 24) return { value: addl, off };
+  if (addl === 24) return { value: buf[off], off: off + 1 };
+  if (addl === 25) return { value: (buf[off] << 8) | buf[off + 1], off: off + 2 };
+  if (addl === 26)
+    return {
+      value: (buf[off] * 2 ** 24) + (buf[off + 1] << 16) + (buf[off + 2] << 8) + buf[off + 3],
+      off: off + 4,
+    };
+  if (addl === 27) throw new Error('uint64 not supported in header');
+  throw new Error('indefinite lengths not supported');
+}
+
+function skipItem(buf: Uint8Array, off: number): number {
+  const ib = buf[off];
+  if (ib === undefined) throw new Error('unexpected EOF');
+  const major = ib >>> 5;
+  const addl = ib & 0x1f;
+  off += 1;
+  const readLen = () => {
+    const r = readVarUint(buf, off, addl);
+    off = r.off;
+    return r.value;
+  };
+
+  switch (major) {
+    case 0: // unsigned
+    case 1: // negative
+      if (addl >= 24) off = readVarUint(buf, off, addl).off;
+      return off;
+    case 2: // byte string
+    case 3: { // text string
+      const len = readLen();
+      return off + len;
+    }
+    case 4: { // array
+      const len = readLen();
+      for (let i = 0; i < len; i++) off = skipItem(buf, off);
+      return off;
+    }
+    case 5: { // map
+      const len = readLen();
+      for (let i = 0; i < len; i++) {
+        off = skipItem(buf, off); // key
+        off = skipItem(buf, off); // value
+      }
+      return off;
+    }
+    case 6: { // tag
+      // skip tag and the tagged item
+      if (addl >= 24) off = readVarUint(buf, off, addl).off;
+      return skipItem(buf, off);
+    }
+    case 7: // simple/float/bool/null
+      if (addl === 24) return off + 1; // simple(8)
+      if (addl === 25) return off + 2; // half float
+      if (addl === 26) return off + 4; // float
+      if (addl === 27) return off + 8; // double
+      return off; // simple values (true/false/null)
+    default:
+      throw new Error('unknown major type');
+  }
+}
+
+export function parseFramedFrame<T = unknown>(framed: Uint8Array): { header: any; body: T } {
+  if (framed.byteLength < 5) throw new Error('frame too small');
+  const total = readU32BE(framed, 0);
+  if (total !== framed.byteLength - 4) throw new Error('length prefix mismatch');
+  const payload = framed.subarray(4);
+
+  const hdrEnd = skipItem(payload, 0);
+  const header = dagCbor.decode(payload.subarray(0, hdrEnd));
+  const body = dagCbor.decode(payload.subarray(hdrEnd)) as T;
+  return { header, body };
+}
+

package/src/lib/firehose/validation.ts

@@ -0,0 +1,9 @@
+import { createErrorFrame } from './frames';
+
+export function checkCursor(cursor: number, currentSeq: number): Uint8Array | null {
+  if (Number.isFinite(cursor) && Number.isFinite(currentSeq) && cursor > currentSeq) {
+    return createErrorFrame('FutureCursor', 'Cursor is ahead of current sequence').toFramedBytes();
+  }
+  return null;
+}
+

package/src/lib/handle.ts

@@ -0,0 +1,90 @@
+/**
+ * Handle validation and normalization utilities
+ *
+ * Handles must:
+ * - Be lowercase
+ * - Contain only alphanumeric characters, dots, and hyphens
+ * - Not start or end with dots or hyphens
+ * - Have valid TLD
+ */
+
+/**
+ * Validate handle format
+ */
+export function isValidHandle(handle: string): boolean {
+  if (!handle || typeof handle !== 'string') {
+    return false;
+  }
+
+  // Must be lowercase
+  if (handle !== handle.toLowerCase()) {
+    return false;
+  }
+
+  // Length constraints (3-253 characters)
+  if (handle.length < 3 || handle.length > 253) {
+    return false;
+  }
+
+  // Must match pattern: alphanumeric, dots, hyphens
+  // Cannot start/end with dot or hyphen
+  const handleRegex = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+  if (!handleRegex.test(handle)) {
+    return false;
+  }
+
+  // Must have at least one dot (domain requirement)
+  if (!handle.includes('.')) {
+    return false;
+  }
+
+  // Check TLD is valid (at least 2 characters)
+  const parts = handle.split('.');
+  const tld = parts[parts.length - 1];
+  if (tld.length < 2) {
+    return false;
+  }
+
+  // No consecutive dots
+  if (handle.includes('..')) {
+    return false;
+  }
+
+  // No consecutive hyphens
+  if (handle.includes('--')) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Normalize handle (lowercase, trim)
+ */
+export function normalizeHandle(handle: string): string {
+  return handle.toLowerCase().trim();
+}
+
+/**
+ * Validate and normalize handle
+ */
+export function validateAndNormalizeHandle(handle: string): string | null {
+  const normalized = normalizeHandle(handle);
+  return isValidHandle(normalized) ? normalized : null;
+}
+
+/**
+ * Extract domain from handle
+ */
+export function getHandleDomain(handle: string): string {
+  const parts = handle.split('.');
+  return parts.slice(-2).join('.');
+}
+
+/**
+ * Check if handle is a subdomain
+ */
+export function isSubdomain(handle: string): boolean {
+  const parts = handle.split('.');
+  return parts.length > 2;
+}

package/src/lib/jwt.ts

@@ -0,0 +1,150 @@
+import type { Env } from '../env';
+
+export interface JwtClaims {
+  sub: string; // DID
+  handle?: string;
+  scope?: string;
+  aud?: string;
+  jti?: string;
+  t: 'access' | 'refresh';
+}
+
+// JWT
+export async function signJwt(env: Env, claims: JwtClaims, kind: 'access' | 'refresh'): Promise<string> {
+  const iat = Math.floor(Date.now() / 1000);
+  const ttlAccess = Number((env.PDS_ACCESS_TTL_SEC as string | undefined) ?? 3600);
+  const ttlRefresh = Number((env.PDS_REFRESH_TTL_SEC as string | undefined) ?? 30 * 24 * 3600);
+  const exp = iat + (kind === 'access' ? ttlAccess : ttlRefresh);
+
+  // Build proper JWT claims
+  const payload: Record<string, unknown> = {
+    iss: env.PDS_HOSTNAME || 'alteran',
+    sub: claims.sub,
+    aud: claims.aud || env.PDS_HOSTNAME || 'alteran',
+    iat,
+    exp,
+    t: kind,
+  };
+
+  // Add optional claims
+  if (claims.handle) payload.handle = claims.handle;
+  if (claims.scope) payload.scope = claims.scope;
+  if (claims.jti) payload.jti = claims.jti;
+
+  const secret = kind === 'access' ? (env.ACCESS_TOKEN_SECRET ?? 'dev-access') : (env.REFRESH_TOKEN_SECRET ?? 'dev-refresh');
+  const algorithm = (env.JWT_ALGORITHM as string | undefined) ?? 'HS256';
+
+  if (algorithm === 'EdDSA') {
+    return await eddsaJwtSign(payload, env);
+  }
+
+  return await hmacJwtSign(payload, secret);
+}
+
+export async function verifyJwt(env: Env, token: string): Promise<{ valid: boolean; payload: any } | null> {
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  const header = JSON.parse(atob(parts[0].replace(/-/g, '+').replace(/_/g, '/')));
+
+  const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
+
+  let ok = false;
+  if (header.alg === 'HS256' && header.typ === 'JWT') {
+    const secret = (payload.t === 'refresh') ? (env.REFRESH_TOKEN_SECRET ?? 'dev-refresh') : (env.ACCESS_TOKEN_SECRET ?? 'dev-access');
+    ok = await hmacJwtVerify(parts[0] + '.' + parts[1], parts[2], secret);
+  } else if (header.alg === 'EdDSA' && header.typ === 'JWT') {
+    ok = await eddsaJwtVerify(parts[0] + '.' + parts[1], parts[2], env);
+  } else {
+    return null;
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (!ok || (payload.exp && now > payload.exp)) return null;
+  return { valid: true, payload };
+}
+
+async function hmacJwtSign(payload: any, secret: string): Promise<string> {
+  const enc = new TextEncoder();
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const h = b64url(enc.encode(JSON.stringify(header)));
+  const p = b64url(enc.encode(JSON.stringify(payload)));
+  const data = `${h}.${p}`;
+  const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(data));
+  const s = b64url(new Uint8Array(sig));
+  return `${h}.${p}.${s}`;
+}
+
+async function hmacJwtVerify(data: string, sigB64: string, secret: string): Promise<boolean> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+  const ok = await crypto.subtle.verify('HMAC', key, b64urlDecode(sigB64), enc.encode(data));
+  return !!ok;
+}
+
+async function eddsaJwtSign(payload: any, env: Env): Promise<string> {
+  const enc = new TextEncoder();
+  const header = { alg: 'EdDSA', typ: 'JWT' };
+  const h = b64url(enc.encode(JSON.stringify(header)));
+  const p = b64url(enc.encode(JSON.stringify(payload)));
+  const data = `${h}.${p}`;
+
+  // Import Ed25519 private key from env
+  const keyData = env.JWT_ED25519_PRIVATE_KEY as string | undefined;
+  if (!keyData) {
+    throw new Error('JWT_ED25519_PRIVATE_KEY not configured');
+  }
+
+  // Decode base64 private key
+  const keyBytes = b64urlDecode(keyData);
+  const key = await crypto.subtle.importKey(
+    'raw',
+    keyBytes,
+    { name: 'Ed25519', namedCurve: 'Ed25519' } as any,
+    false,
+    ['sign']
+  );
+
+  const sig = await crypto.subtle.sign('Ed25519', key, enc.encode(data));
+  const s = b64url(new Uint8Array(sig));
+  return `${h}.${p}.${s}`;
+}
+
+async function eddsaJwtVerify(data: string, sigB64: string, env: Env): Promise<boolean> {
+  const enc = new TextEncoder();
+
+  // Import Ed25519 public key from env
+  const keyData = env.JWT_ED25519_PUBLIC_KEY as string | undefined;
+  if (!keyData) {
+    return false;
+  }
+
+  const keyBytes = b64urlDecode(keyData);
+  const key = await crypto.subtle.importKey(
+    'raw',
+    keyBytes,
+    { name: 'Ed25519', namedCurve: 'Ed25519' } as any,
+    false,
+    ['verify']
+  );
+
+  const ok = await crypto.subtle.verify('Ed25519', key, b64urlDecode(sigB64), enc.encode(data));
+  return !!ok;
+}
+
+function b64url(bytes: ArrayBuffer | Uint8Array): string {
+  const b = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let s = '';
+  for (let i = 0; i < b.length; i++) {
+    s += String.fromCharCode(b[i]);
+  }
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function b64urlDecode(s: string): Uint8Array {
+  const pad = s.length % 4 === 2 ? '==' : s.length % 4 === 3 ? '=' : '';
+  const bin = atob(s.replace(/-/g, '+').replace(/_/g, '/') + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}

package/src/lib/logger.ts

@@ -0,0 +1,73 @@
+/**
+ * Structured Logging
+ * Provides JSON-formatted logs with levels and context
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogContext {
+  requestId?: string;
+  path?: string;
+  method?: string;
+  status?: number;
+  duration?: number;
+  error?: string;
+  stack?: string;
+  [key: string]: unknown;
+}
+
+export class Logger {
+  constructor(private context: LogContext = {}) {}
+
+  private log(level: LogLevel, message: string, extra: LogContext = {}) {
+    const entry = {
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      ...this.context,
+      ...extra,
+    };
+
+    console.log(JSON.stringify(entry));
+  }
+
+  debug(message: string, context?: LogContext) {
+    this.log('debug', message, context);
+  }
+
+  info(message: string, context?: LogContext) {
+    this.log('info', message, context);
+  }
+
+  warn(message: string, context?: LogContext) {
+    this.log('warn', message, context);
+  }
+
+  error(message: string, error?: Error | unknown, context?: LogContext) {
+    const errorContext: LogContext = { ...context };
+
+    if (error instanceof Error) {
+      errorContext.error = error.message;
+      errorContext.stack = error.stack;
+      errorContext.errorName = error.name;
+    } else if (error) {
+      errorContext.error = String(error);
+    }
+
+    this.log('error', message, errorContext);
+  }
+
+  child(context: LogContext): Logger {
+    return new Logger({ ...this.context, ...context });
+  }
+}
+
+// Global logger instance
+export const logger = new Logger();
+
+/**
+ * Create a request-scoped logger
+ */
+export function createRequestLogger(requestId: string, path: string, method: string): Logger {
+  return logger.child({ requestId, path, method });
+}