serverless-ircd 0.10.0 → 0.11.0

package/apps/aws-stack/tests/stack.test.ts

@@ -23,6 +23,23 @@ import type { StaticSiteProps } from '../src/static-site.js';
 /** All five table names that must exist in the stack (PLAN §4). */
 const TABLE_NAMES = ['ChannelMembers', 'ChannelMeta', 'Connections', 'Nicks', 'Services'] as const;
 
+/**
+ * Raw synthesised CloudFormation node for a DynamoDB table. `DeletionPolicy`
+ * and `UpdateReplacePolicy` live at the resource root (siblings of
+ * `Properties`), so they are NOT visible via `Template.hasResourceProperties`
+ * — tests that assert the removal policy inspect the full node.
+ */
+type DynamoTableResource = {
+  Type: string;
+  DeletionPolicy?: string;
+  UpdateReplacePolicy?: string;
+  Properties?: {
+    TableName?: string;
+    PointInTimeRecoverySpecification?: { PointInTimeRecoveryEnabled?: boolean };
+    DeletionProtectionEnabled?: boolean;
+  };
+};
+
 function makeTemplate(): { app: App; stack: Stack; template: Template } {
   const app = new App();
   const stack = new IrcAwsStack(app, 'TestStack');
@@ -99,7 +116,12 @@ describe('IrcAwsStack — DynamoDB tables', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::DynamoDB::Table', {
       TableName: 'Connections',
-      AttributeDefinitions: [{ AttributeName: 'connectionId', AttributeType: 'S' }],
+      // connectionId (base key) plus the per-IP admission GSI keys.
+      AttributeDefinitions: [
+        { AttributeName: 'connectionId', AttributeType: 'S' },
+        { AttributeName: 'sourceIp', AttributeType: 'S' },
+        { AttributeName: 'connectedSince', AttributeType: 'N' },
+      ],
       KeySchema: [{ AttributeName: 'connectionId', KeyType: 'HASH' }],
     });
   });
@@ -153,6 +175,173 @@ describe('IrcAwsStack — DynamoDB tables', () => {
   });
 });
 
+describe('IrcAwsStack — DynamoDB table protection (RETAIN + PITR + deletion protection)', () => {
+  /**
+   * State-bearing tables hold user data (nicks, services credentials,
+   * channel state, membership) and MUST survive a mistaken `cdk destroy`,
+   * a stack-name collision, or a stray `aws dynamodb delete-table` from a
+   * compromised credential. `Connections` is the one exception: its rows
+   * are ephemeral per-connection records (TTL-reaped, sweeper-cleaned), so
+   * it stays DESTROY with no PITR and no deletion protection.
+   */
+  const STATE_TABLES = ['ChannelMembers', 'ChannelMeta', 'Nicks', 'Services'] as const;
+  const EPHEMERAL_TABLE = 'Connections';
+
+  /**
+   * Returns the synthesised `AWS::DynamoDB::Table` resources keyed by their
+   * physical `TableName`. Each value is the raw CloudFormation resource
+   * node, so `DeletionPolicy`, `UpdateReplacePolicy`, and the protection
+   * properties under `Properties` are all inspectable. `DeletionPolicy` lives
+   * at the resource root (sibling of `Properties`), so it is NOT visible to
+   * `hasResourceProperties` — the raw node is required.
+   */
+  function dynamoTablesByName(template: Template): Record<
+    string,
+    {
+      Type: string;
+      DeletionPolicy?: string;
+      UpdateReplacePolicy?: string;
+      Properties?: {
+        TableName?: string;
+        PointInTimeRecoverySpecification?: { PointInTimeRecoveryEnabled?: boolean };
+        DeletionProtectionEnabled?: boolean;
+      };
+    }
+  > {
+    const tmpl = template.toJSON() as { Resources?: Record<string, unknown> };
+    const out: Record<string, DynamoTableResource> = {};
+    for (const raw of Object.values(tmpl.Resources ?? {})) {
+      const res = raw as { Type?: string; Properties?: { TableName?: string } };
+      if (res.Type !== 'AWS::DynamoDB::Table') {
+        continue;
+      }
+      const name = res.Properties?.TableName;
+      if (typeof name === 'string') {
+        out[name] = raw as DynamoTableResource;
+      }
+    }
+    return out;
+  }
+
+  describe('default synth (no flags)', () => {
+    it.each(STATE_TABLES)('RETAINs the %s table (DeletionPolicy=Retain)', (name) => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[name]?.DeletionPolicy).toBe('Retain');
+    });
+
+    it.each(STATE_TABLES)('sets UpdateReplacePolicy=Retain on the %s table', (name) => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[name]?.UpdateReplacePolicy).toBe('Retain');
+    });
+
+    it('keeps the Connections table DESTROY (DeletionPolicy=Delete)', () => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[EPHEMERAL_TABLE]?.DeletionPolicy).toBe('Delete');
+    });
+
+    it.each(STATE_TABLES)('enables point-in-time recovery on the %s table', (name) => {
+      const { template } = makeTemplate();
+      expect(
+        dynamoTablesByName(template)[name]?.Properties?.PointInTimeRecoverySpecification
+          ?.PointInTimeRecoveryEnabled,
+      ).toBe(true);
+    });
+
+    it('does NOT enable point-in-time recovery on the Connections table', () => {
+      const { template } = makeTemplate();
+      expect(
+        dynamoTablesByName(template)[EPHEMERAL_TABLE]?.Properties?.PointInTimeRecoverySpecification,
+      ).toBeUndefined();
+    });
+
+    it.each(STATE_TABLES)('enables deletion protection on the %s table', (name) => {
+      const { template } = makeTemplate();
+      expect(dynamoTablesByName(template)[name]?.Properties?.DeletionProtectionEnabled).toBe(true);
+    });
+
+    it('does NOT enable deletion protection on the Connections table', () => {
+      const { template } = makeTemplate();
+      expect(
+        dynamoTablesByName(template)[EPHEMERAL_TABLE]?.Properties?.DeletionProtectionEnabled,
+      ).toBeUndefined();
+    });
+  });
+
+  describe('allowTableDeletion=true synth (teardown mode)', () => {
+    function makeTeardownTemplate(): Template {
+      const app = new App();
+      const stack = new IrcAwsStack(app, 'TestStack', { allowTableDeletion: true });
+      return Template.fromStack(stack);
+    }
+
+    it.each(STATE_TABLES)('flips the %s table to DESTROY (DeletionPolicy=Delete)', (name) => {
+      const template = makeTeardownTemplate();
+      expect(dynamoTablesByName(template)[name]?.DeletionPolicy).toBe('Delete');
+    });
+
+    it.each(STATE_TABLES)('disables deletion protection on the %s table', (name) => {
+      const template = makeTeardownTemplate();
+      expect(dynamoTablesByName(template)[name]?.Properties?.DeletionProtectionEnabled).toBe(false);
+    });
+
+    it('keeps the Connections table DESTROY', () => {
+      const template = makeTeardownTemplate();
+      expect(dynamoTablesByName(template)[EPHEMERAL_TABLE]?.DeletionPolicy).toBe('Delete');
+    });
+
+    it('still keeps point-in-time recovery enabled on state tables in teardown mode', () => {
+      // allowTableDeletion and enablePitr are independent flags: a legitimate
+      // teardown still keeps PITR on (it is harmless and the data is still
+      // recoverable up until the table is actually deleted). Disabling PITR
+      // is a separate, deliberate opt-in via enablePitr=false.
+      const template = makeTeardownTemplate();
+      for (const name of STATE_TABLES) {
+        expect(
+          dynamoTablesByName(template)[name]?.Properties?.PointInTimeRecoverySpecification
+            ?.PointInTimeRecoveryEnabled,
+        ).toBe(true);
+      }
+    });
+  });
+
+  describe('enablePitr=false synth (PITR disabled)', () => {
+    function makeNoPitrTemplate(): Template {
+      const app = new App();
+      const stack = new IrcAwsStack(app, 'TestStack', { enablePitr: false });
+      return Template.fromStack(stack);
+    }
+
+    it.each(STATE_TABLES)('disables point-in-time recovery on the %s table', (name) => {
+      const template = makeNoPitrTemplate();
+      expect(
+        dynamoTablesByName(template)[name]?.Properties?.PointInTimeRecoverySpecification
+          ?.PointInTimeRecoveryEnabled,
+      ).toBe(false);
+    });
+
+    it('still does NOT enable point-in-time recovery on the Connections table', () => {
+      const template = makeNoPitrTemplate();
+      expect(
+        dynamoTablesByName(template)[EPHEMERAL_TABLE]?.Properties?.PointInTimeRecoverySpecification,
+      ).toBeUndefined();
+    });
+
+    it('keeps state tables RETAIN with deletion protection when PITR is disabled', () => {
+      // enablePitr=false narrows ONLY the PITR knob; the RETAIN +
+      // deletion-protection guarantees are independent of PITR and must
+      // remain on so a disabled-PITR deploy is still protected from
+      // accidental stack deletion.
+      const template = makeNoPitrTemplate();
+      for (const name of STATE_TABLES) {
+        expect(dynamoTablesByName(template)[name]?.DeletionPolicy).toBe('Retain');
+        expect(dynamoTablesByName(template)[name]?.Properties?.DeletionProtectionEnabled).toBe(
+          true,
+        );
+      }
+    });
+  });
+});
+
 describe('IrcAwsStack — API Gateway v2 WebSocket API', () => {
   it('creates a WebSocket protocol API Gateway v2 API', () => {
     const { template } = makeTemplate();
@@ -346,15 +535,12 @@ describe('IrcAwsStack — API Gateway logging', () => {
     ).toBe(true);
   });
 
-  it('grants the logging role CloudWatch Logs write access across ALL log groups', () => {
-    // APIGW writes execution logs to its OWN AWS/ApiGateway... log groups
-    // (separate from this stack's access-log group), so the role must be
-    // able to write broadly — a single-log-group ARN scope is rejected by
-    // APIGW account-role validation. Defined inline (the
-    // AmazonAPIGatewayPushToCloudWatchLogs managed policy is not available
-    // in every partition); CDK renders the statement as a separate
-    // AWS::IAM::Policy attached to the role.
-    const { template } = makeTemplate();
+  /**
+   * Flattens the IAM actions granted by the inline policy CDK attaches to
+   * the `ApiGatewayLoggingRole` (`addToPolicy` renders as a separate
+   * `AWS::IAM::Policy` resource referencing the role).
+   */
+  function loggingRoleActions(template: Template): string[] {
     const roles = template.findResources('AWS::IAM::Role') as Record<string, unknown>;
     const loggingRoleEntry = Object.entries(roles).find(([id]) =>
       id.startsWith('ApiGatewayLoggingRole'),
@@ -379,12 +565,54 @@ describe('IrcAwsStack — API Gateway logging', () => {
     const stmts = attached?.Properties?.PolicyDocument?.Statement ?? [];
     const flat = (a: string | string[] | undefined): string[] =>
       Array.isArray(a) ? a : a !== undefined ? [a] : [];
-    const actions = JSON.stringify(stmts.flatMap((s) => flat(s.Action)));
-    const resources = JSON.stringify(stmts.flatMap((s) => flat(s.Resource as string[])));
-    expect(actions).toContain('logs:PutLogEvents');
-    expect(actions).toContain('logs:CreateLogGroup');
-    // Broad scope — NOT narrowed to a single log-group ARN.
-    expect(resources).toContain('*');
+    return stmts.flatMap((s) => flat(s.Action));
+  }
+
+  it('grants the logging role exactly the three CloudWatch Logs WRITE actions across ALL log groups', () => {
+    // APIGW writes execution logs to its OWN AWS/ApiGateway... log groups
+    // (separate from this stack's access-log group), so the role must be
+    // able to write broadly — a single-log-group ARN scope is rejected by
+    // APIGW account-role validation. The grant set is EXACTLY the three
+    // write actions APIGW needs; the legacy inline policy additionally
+    // carried Describe* actions, which let a compromised role enumerate
+    // (and, via the managed policy AWS offers for this purpose, read)
+    // arbitrary log groups in the account. Exact-set assertion so any
+    // future widening fails this test.
+    const { template } = makeTemplate();
+    expect([...loggingRoleActions(template)].sort()).toEqual([
+      'logs:CreateLogGroup',
+      'logs:CreateLogStream',
+      'logs:PutLogEvents',
+    ]);
+  });
+
+  it('does not grant the logging role any log-enumeration or log-read actions', () => {
+    const { template } = makeTemplate();
+    const actions = loggingRoleActions(template);
+    expect(
+      actions.filter((a) => /^logs:(Describe|Get|Filter)/.test(a)),
+      'logging role must not enumerate or read log groups',
+    ).toEqual([]);
+  });
+
+  it('attaches no AWS-managed policies to the logging role (documented inline decision)', () => {
+    // Decision record: the AmazonAPIGatewayPushToCloudWatchLogs managed
+    // policy was considered and REJECTED. Its fixed grant set is broader
+    // than the tightened inline policy — it still grants DescribeLogGroups
+    // and DescribeLogStreams (the actions this stack deliberately drops)
+    // plus GetLogEvents and FilterLogEvents, all on Resource '*' — and AWS
+    // can widen its contents without this stack being re-reviewed. The
+    // inline policy keeps the grant set exact and auditable at synth time.
+    const { template } = makeTemplate();
+    const roles = template.findResources('AWS::IAM::Role') as Record<
+      string,
+      { Properties?: { ManagedPolicyArns?: unknown } }
+    >;
+    const loggingRole = Object.entries(roles).find(([id]) =>
+      id.startsWith('ApiGatewayLoggingRole'),
+    );
+    expect(loggingRole, 'expected an ApiGatewayLoggingRole').toBeDefined();
+    expect(loggingRole?.[1]?.Properties?.ManagedPolicyArns).toBeUndefined();
   });
 });
 
@@ -1012,6 +1240,101 @@ describe('IrcAwsStack — TCP+TLS NLB adapter', () => {
       });
     });
 
+    /**
+     * Collects every IAM policy statement attached to the NLB handler
+     * Lambda's execution role — the role's inline `Policies` plus every
+     * separate `AWS::IAM::Policy` resource referencing it (CDK renders
+     * `grant*` calls as the role's `DefaultPolicy` resource).
+     */
+    function nlbRoleStatements(template: Template): Array<Record<string, unknown>> {
+      const fns = template.findResources('AWS::Lambda::Function') as Record<
+        string,
+        { Properties?: { Role?: { 'Fn::GetAtt'?: string[] } | { Ref?: string } } }
+      >;
+      const nlbFn = Object.entries(fns).find(([id]) => id.startsWith('IrcNlbHandler'));
+      if (nlbFn === undefined) {
+        throw new Error('No Lambda with logical id starting with "IrcNlbHandler"');
+      }
+      const role = nlbFn[1]?.Properties?.Role as
+        | { 'Fn::GetAtt'?: string[]; Ref?: string }
+        | undefined;
+      const getAtt = role?.['Fn::GetAtt'];
+      const roleLogicalId = Array.isArray(getAtt) ? getAtt[0] : role?.Ref;
+      if (typeof roleLogicalId !== 'string') {
+        throw new Error('IrcNlbHandler Lambda has no resolvable execution role');
+      }
+      const statements: Array<Record<string, unknown>> = [];
+      const roles = template.findResources('AWS::IAM::Role') as Record<
+        string,
+        { Properties?: { Policies?: Array<{ PolicyDocument?: { Statement?: unknown[] } }> } }
+      >;
+      for (const inline of roles[roleLogicalId]?.Properties?.Policies ?? []) {
+        statements.push(
+          ...((inline.PolicyDocument?.Statement ?? []) as Array<Record<string, unknown>>),
+        );
+      }
+      const policies = template.findResources('AWS::IAM::Policy') as Record<
+        string,
+        {
+          Properties?: {
+            Roles?: Array<{ Ref?: string }>;
+            PolicyDocument?: { Statement?: unknown[] };
+          };
+        }
+      >;
+      for (const policy of Object.values(policies)) {
+        const attached = (policy.Properties?.Roles ?? []).some((r) => r.Ref === roleLogicalId);
+        if (attached) {
+          statements.push(
+            ...((policy.Properties?.PolicyDocument?.Statement ?? []) as Array<
+              Record<string, unknown>
+            >),
+          );
+        }
+      }
+      return statements;
+    }
+
+    /** True when a statement's Action includes `execute-api:ManageConnections`. */
+    function managesConnections(stmt: Record<string, unknown>): boolean {
+      const action = stmt.Action;
+      return (
+        action === 'execute-api:ManageConnections' ||
+        (Array.isArray(action) && action.includes('execute-api:ManageConnections'))
+      );
+    }
+
+    it('grants the NLB handler Lambda execute-api:ManageConnections on the stage', () => {
+      // The NLB stream handler passes MANAGEMENT_URL into AwsRuntime and
+      // fans channel messages out to *other* connections via
+      // ApiGatewayManagementApi.postToConnection — including wss clients
+      // on the API Gateway transport. Without the stage grant on the NLB
+      // handler's own execution role, every such cross-transport delivery
+      // fails with 403.
+      const { template } = makeTcpTemplate();
+      const manages = nlbRoleStatements(template).filter(managesConnections);
+      expect(
+        manages.length,
+        'NLB handler role must be granted execute-api:ManageConnections',
+      ).toBeGreaterThan(0);
+    });
+
+    it('scopes the NLB handler ManageConnections grant to this stack API stage connections', () => {
+      // Least privilege: the grant must target THIS stack's WebSocket API
+      // stage connections resource (…/apis/<api>/prod/*/@connections/*),
+      // never a wildcard API or account-wide resource.
+      const { template } = makeTcpTemplate();
+      const apiIds = Object.keys(template.findResources('AWS::ApiGatewayV2::Api')).filter((id) =>
+        id.startsWith('IrcWsApi'),
+      );
+      expect(apiIds).toHaveLength(1);
+      const manages = nlbRoleStatements(template).filter(managesConnections);
+      const resourceJson = JSON.stringify(manages.map((s) => s.Resource));
+      expect(resourceJson).toContain('@connections');
+      expect(resourceJson).toContain('/prod/');
+      expect(resourceJson).toContain(apiIds[0] ?? '');
+    });
+
     it('still creates the wss WebSocket API (both transports coexist)', () => {
       const { template } = makeTcpTemplate();
       template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
@@ -1122,3 +1445,114 @@ describe('IrcAwsStack — web client hosting (StaticSite)', () => {
     });
   });
 });
+
+describe('IrcAwsStack — API Gateway stage throttling', () => {
+  it('exposes ApiThrottlingRateLimit as a configurable Number parameter (default 100)', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).ApiThrottlingRateLimit;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('Number');
+    // CfnParameter renders a numeric default as a JSON number.
+    expect(Number(p?.Default)).toBe(100);
+    expect(typeof p?.Description).toBe('string');
+    expect(p?.Description?.length).toBeGreaterThan(0);
+  });
+
+  it('exposes ApiThrottlingBurstLimit as a configurable Number parameter (default 200)', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).ApiThrottlingBurstLimit;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('Number');
+    expect(Number(p?.Default)).toBe(200);
+    expect(typeof p?.Description).toBe('string');
+  });
+
+  it('wires the stage default-route throttling to the parameters (Ref)', () => {
+    // Stage-level throttling is the global backstop behind the per-IP
+    // admission gates: it bounds aggregate request rate into the API
+    // (connect floods included) before a Lambda invocation is billed.
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::Stage', {
+      DefaultRouteSettings: {
+        ThrottlingRateLimit: { Ref: 'ApiThrottlingRateLimit' },
+        ThrottlingBurstLimit: { Ref: 'ApiThrottlingBurstLimit' },
+      },
+    });
+  });
+});
+
+describe('IrcAwsStack — Connections sourceIp GSI', () => {
+  it('adds a sourceIp+connectedSince GSI to the Connections table', () => {
+    // The per-IP admission gates ($connect simultaneous cap + rate
+    // window, NLB new-flow rate) consult this index; without it the
+    // handler would need a full-table Scan per connect.
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: 'Connections',
+      GlobalSecondaryIndexes: [
+        {
+          IndexName: 'sourceIp-connectedSince',
+          KeySchema: [
+            { AttributeName: 'sourceIp', KeyType: 'HASH' },
+            { AttributeName: 'connectedSince', KeyType: 'RANGE' },
+          ],
+        },
+      ],
+    });
+  });
+});
+
+describe('IrcAwsStack — WAF rate-based rule on $connect', () => {
+  /** Synths a stack with the optional edge rate limit configured. */
+  function makeWafTemplate(limit: number): Template {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { wafConnectRateLimit: limit });
+    return Template.fromStack(stack);
+  }
+
+  it('emits no WebACL by default (the knob is opt-in)', () => {
+    const { template } = makeTemplate();
+    template.resourceCountIs('AWS::WAFv2::WebACL', 0);
+    template.resourceCountIs('AWS::WAFv2::WebACLAssociation', 0);
+  });
+
+  it('emits a REGIONAL WebACL with a per-IP rate-based rule when the knob is set', () => {
+    // WAF on a WebSocket API only inspects the initial HTTP upgrade —
+    // the `$connect` route — so a plain rate-based statement is
+    // effectively scoped to connection establishment.
+    const template = makeWafTemplate(2000);
+    template.resourceCountIs('AWS::WAFv2::WebACL', 1);
+    template.hasResourceProperties('AWS::WAFv2::WebACL', {
+      Scope: 'REGIONAL',
+      DefaultAction: { Allow: {} },
+      Rules: [
+        {
+          Name: 'ConnectRateLimit',
+          Priority: 0,
+          Action: { Block: {} },
+          Statement: {
+            RateBasedStatement: { Limit: 2000, AggregateKeyType: 'IP' },
+          },
+        },
+      ],
+    });
+  });
+
+  it('associates the WebACL with the WebSocket stage', () => {
+    const template = makeWafTemplate(2000);
+    template.resourceCountIs('AWS::WAFv2::WebACLAssociation', 1);
+    const assoc = template.findResources('AWS::WAFv2::WebACLAssociation') as Record<
+      string,
+      { Properties?: { ResourceArn?: unknown; WebACLArn?: unknown } }
+    >;
+    const entry = Object.values(assoc)[0];
+    expect(entry?.Properties?.WebACLArn).toBeDefined();
+    // ResourceArn must be the API Gateway stage ARN (Fn::Join over the
+    // partition/region refs + the WebSocket Api Ref + the stage name),
+    // not a dangling literal.
+    const arn = JSON.stringify(entry?.Properties?.ResourceArn);
+    expect(arn).toContain('apigateway');
+    expect(arn).toContain('/stages/prod');
+    expect(arn).toContain('IrcWsApi');
+  });
+});

package/apps/cf-tcp-container/Dockerfile

@@ -1,14 +1,24 @@
 # Cloudflare Container / Docker image for the ServerlessIRCd TCP origin.
 #
-# Spectrum terminates TLS at the edge and forwards plaintext TCP to this
-# container. The container runs the IRC core (ConnectionActor +
-# InMemoryRuntime) over the TcpByteStreamTransport seam on port 6667.
+# TLS terminates INSIDE this container on :6697 (Spectrum runs in
+# `tls_mode = "full"`, re-encrypting edge→origin) — no plaintext IRC
+# ever crosses the origin network. The container runs the IRC core
+# (ConnectionActor + InMemoryRuntime) over the TcpByteStreamTransport
+# seam behind its own TLS listener.
 #
 # Build context: the repository root (monorepo). The container needs the
 # irc-core, irc-server, and in-memory-runtime packages.
 #
 #   docker build -f apps/cf-tcp-container/Dockerfile -t sirc-tcp-origin .
-#   docker run -p 6667:6667 -e SERVER_NAME=irc.example.com sirc-tcp-origin
+#   docker run -p 6697:6697 \
+#     -v $(pwd)/certs:/data/certs:ro \
+#     -e SERVER_NAME=irc.example.com sirc-tcp-origin
+#
+# Certificates: mount a PEM cert/key pair at /data/certs/ (the image
+# defaults TLS_CERT_PATH=/data/certs/tls.pem, TLS_KEY_PATH=/data/certs/
+# tls.key). Let's Encrypt, Bring-Your-Own, and Cloudflare Origin Certs
+# are all supported — see docs/Cloudflare-TCP-Deployment.md. Cert files
+# must be readable by UID 1000 (node).
 #
 # For Cloudflare Containers deployment, the same image is referenced from
 # wrangler.toml.
@@ -57,13 +67,35 @@ COPY --from=builder /app/apps/cf-tcp-container/dist/ apps/cf-tcp-container/dist/
 RUN corepack enable && corepack prepare pnpm@11.17.0 --activate && \
     pnpm install --frozen-lockfile --prod
 
+# Runtime-writable state: the persistence snapshot lives in /data, and the
+# runtime process runs as the unprivileged `node` user — so the directory
+# must exist and be node-owned before privileges drop (chown needs root).
+RUN mkdir -p /data && chown node:node /data
+
 # Persistence volume: Spectrum-origin channel state survives restarts.
 VOLUME ["/data"]
 
-EXPOSE 6667
+# Cert files for TLS termination at the origin: mount the PEM pair at
+# /data/certs/ (see ENV defaults below) — Let's Encrypt, BYO, or a
+# Cloudflare Origin Cert all work. Any cert mount must be readable by
+# UID 1000 (node) — mount them owned by 1000:1000.
+
+# Drop root: the IRC stack (parser + actor + transport) handles untrusted
+# input, so it must not run as UID 0. node:24-slim ships the non-root
+# `node` user (UID 1000) out of the box.
+USER node
+
+EXPOSE 6697
 
+# The image is a production origin by default: the config loader then
+# refuses to boot without TLS material (no silent plaintext fallback).
+ENV NODE_ENV=production
 ENV TCP_PORT=6667
 ENV TCP_HOST=0.0.0.0
 ENV PERSISTENCE_PATH=/data/state.json
+# Documented cert mount path (override per-deploy via TLS_CERT_PATH /
+# TLS_KEY_PATH if the pair lives elsewhere).
+ENV TLS_CERT_PATH=/data/certs/tls.pem
+ENV TLS_KEY_PATH=/data/certs/tls.key
 
 CMD ["node", "--enable-source-maps", "apps/cf-tcp-container/dist/main.js"]

package/apps/cf-tcp-container/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-tcp-container",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Cloudflare Container TCP origin for the irc+tls :6697 transport — Spectrum terminates TLS at the edge, this container runs the IRC core over plaintext TCP",
   "license": "BSD-3-Clause",
@@ -10,7 +10,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "start": "node --enable-source-maps ./dist/main.js",
-    "deploy": "wrangler deploy",
+    "deploy": "node ../../tools/ci-hardening/dist/cf-deploy-cli.js wrangler.toml",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
@@ -21,6 +21,11 @@
     "@serverless-ircd/irc-core": "workspace:*",
     "@serverless-ircd/irc-server": "workspace:*"
   },
+  "proxyProtocol": {
+    "version": 1,
+    "parser": "hand-rolled (src/proxy-protocol.ts)",
+    "rationale": "PROXY protocol v1 is a single fixed-format ASCII line, fully validated in ~40 lines; no npm proxy-protocol dependency is pulled onto the connection hot path (supply-chain surface > value)."
+  },
   "devDependencies": {
     "@cloudflare/containers": "^0.1.0",
     "@types/node": "^26.1.1",