serverless-ircd 0.9.0 → 0.11.0

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

@@ -0,0 +1,491 @@
+/**
+ * Synth-time assertions for the `StaticSite` construct (the AWS web-client
+ * hosting substrate: a private S3 bucket fronted by a CloudFront
+ * distribution with Origin Access Control).
+ *
+ * The web client (Kiwi SPA + landing page) is the shared `apps/web/dist`
+ * build artifact. On AWS it is served exclusively over CloudFront; the S3
+ * origin bucket is private and grants the distribution via OAC (never
+ * public-read). The landing page at `/` is served via the distribution's
+ * `defaultRootObject` (`/index.html`); SPA client-side routing under
+ * `/webclient/*` is handled by a CloudFront custom error response mapping
+ * S3's 403/404 → `200 /webclient/index.html`.
+ *
+ * These tests synthesise the construct in isolation (via `Template` from
+ * `aws-cdk-lib/assertions`) and assert the exact CloudFormation shape: the
+ * `AWS::CloudFront::Distribution`, `AWS::S3::Bucket`, the OAC resource, the
+ * bucket-policy grant (OAC principal only — no `Public`/`*`), the
+ * 403/404 → `/webclient/index.html` error response, the `/index.html`
+ * default root object, and the `WebsiteURL` output. The integration into
+ * `IrcAwsStack` (opt-in prop) is covered in `stack.test.ts`.
+ */
+
+import { runInNewContext } from 'node:vm';
+import { App, Stack } from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { describe, expect, it } from 'vitest';
+import { StaticSite, type StaticSiteProps } from '../src/static-site.js';
+
+/** Synthesises a `StaticSite` in isolation and returns the assertion Template. */
+function makeSiteTemplate(props: StaticSiteProps = {}): {
+  app: App;
+  stack: Stack;
+  template: Template;
+} {
+  const app = new App();
+  const stack = new Stack(app, 'SiteStack');
+  new StaticSite(stack, 'Site', props);
+  const template = Template.fromStack(stack);
+  return { app, stack, template };
+}
+
+/** Shape of a synthesised CloudFront Distribution's DistributionConfig. */
+type DistConfig = {
+  Origins?: Array<{
+    DomainName?: unknown;
+    S3OriginConfig?: unknown;
+    OriginAccessControlId?: unknown;
+  }>;
+  DefaultCacheBehavior?: {
+    ViewerProtocolPolicy?: string;
+    FunctionAssociations?: Array<{ EventType?: string; FunctionARN?: unknown }>;
+  };
+  Aliases?: string[];
+  CustomErrorResponses?: Array<{
+    ErrorCode?: number;
+    ResponseCode?: number;
+    ResponsePagePath?: string;
+  }>;
+};
+
+/** Extracts the DistributionConfig from the single CloudFront distribution. */
+function distConfig(template: Template): DistConfig {
+  const dists = template.findResources('AWS::CloudFront::Distribution') as Record<
+    string,
+    { Properties?: { DistributionConfig?: DistConfig } }
+  >;
+  const dist = Object.values(dists)[0];
+  return dist?.Properties?.DistributionConfig ?? {};
+}
+
+/**
+ * Result of invoking the synthesised directory-index function: either the
+ * (possibly rewritten) request object (`uri` set), or a 301-redirect
+ * response (`statusCode` + `headers.location`). Kept as a single loose
+ * type with all-optional fields so the per-case tests can read either
+ * shape without per-call casts; the assertions themselves pin the shape.
+ */
+type IndexHandlerResult = {
+  uri?: string;
+  statusCode?: number;
+  statusDescription?: string;
+  headers?: { location?: { value?: string } };
+};
+
+/**
+ * Extracts the synthesized directory-index CloudFront Function's `handler`
+ * entry point as a callable, so its rewrite/redirect logic can be exercised
+ * behaviourally (not just "the source contains 'index.html'"). Uses
+ * `node:vm`'s `runInNewContext` (rather than `eval`/`new Function`, which
+ * lint forbids) to evaluate the inline `FunctionCode` and return the
+ * declared `handler`. Throws if no `AWS::CloudFront::Function` was
+ * synthesised — the calling tests use that as their RED signal.
+ */
+function extractIndexHandler(template: Template): (event: {
+  request: { uri: string; querystring?: Record<string, { value: string }> };
+}) => IndexHandlerResult {
+  const fns = template.findResources('AWS::CloudFront::Function') as Record<
+    string,
+    { Properties?: { FunctionCode?: string } }
+  >;
+  // CDK's `cloudfront.Function` puts `FunctionCode` directly under
+  // `Properties` (NOT nested under `FunctionConfig`, which only holds
+  // `Comment` + `Runtime`).
+  const code = Object.values(fns)[0]?.Properties?.FunctionCode;
+  if (code === undefined) {
+    throw new Error('no AWS::CloudFront::Function with FunctionCode was synthesised');
+  }
+  // The CloudFront function declares `function handler(event) {...}`. Append
+  // a trailing `handler` expression so runInNewContext returns it.
+  return runInNewContext(`${code}\nhandler`, {}) as (event: {
+    request: { uri: string; querystring?: Record<string, { value: string }> };
+  }) => IndexHandlerResult;
+}
+
+/** Returns all bucket-policy statements across the synthesised template. */
+function bucketPolicyStatements(template: Template): Array<{
+  Principal?: unknown;
+  Action?: unknown;
+  Resource?: unknown;
+  Condition?: Record<string, Record<string, unknown>>;
+}> {
+  const policies = template.findResources('AWS::S3::BucketPolicy') as Record<
+    string,
+    { Properties?: { PolicyDocument?: { Statement?: Array<Record<string, unknown>> } } }
+  >;
+  const all: Array<Record<string, unknown>> = [];
+  for (const policy of Object.values(policies)) {
+    all.push(...(policy.Properties?.PolicyDocument?.Statement ?? []));
+  }
+  return all as Array<{
+    Principal?: unknown;
+    Action?: unknown;
+    Resource?: unknown;
+    Condition?: Record<string, Record<string, unknown>>;
+  }>;
+}
+
+describe('StaticSite — CloudFront distribution', () => {
+  it('creates exactly one AWS::CloudFront::Distribution', () => {
+    const { template } = makeSiteTemplate();
+    template.resourceCountIs('AWS::CloudFront::Distribution', 1);
+  });
+
+  it('creates a distribution backed by an S3 origin', () => {
+    const { template } = makeSiteTemplate();
+    const origins = distConfig(template).Origins ?? [];
+    expect(origins.length).toBeGreaterThanOrEqual(1);
+    expect(origins[0]?.S3OriginConfig).toBeDefined();
+  });
+
+  it('redirects HTTP viewers to HTTPS', () => {
+    const { template } = makeSiteTemplate();
+    expect(distConfig(template).DefaultCacheBehavior?.ViewerProtocolPolicy).toBe(
+      'redirect-to-https',
+    );
+  });
+});
+
+describe('StaticSite — private S3 origin bucket', () => {
+  it('creates exactly one AWS::S3::Bucket', () => {
+    const { template } = makeSiteTemplate();
+    template.resourceCountIs('AWS::S3::Bucket', 1);
+  });
+
+  it('never grants public read access (no Public/* principal in any bucket-policy statement)', () => {
+    const { template } = makeSiteTemplate();
+    const statements = bucketPolicyStatements(template);
+    expect(statements.length).toBeGreaterThanOrEqual(1);
+    for (const stmt of statements) {
+      const serialised = JSON.stringify(stmt.Principal);
+      expect(serialised, 'bucket policy must not grant Principal "*"').not.toBe('"*"');
+      expect(serialised, 'bucket policy must not grant Principal AWS "*"').not.toContain(
+        '"AWS":"*"',
+      );
+      expect(serialised, 'bucket policy must not be public-read').not.toContain('Public');
+    }
+  });
+
+  it('grants the CloudFront distribution read access via the OAC service principal', () => {
+    const { template } = makeSiteTemplate();
+    const statements = bucketPolicyStatements(template);
+    const oacGrant = statements.find((s) =>
+      JSON.stringify(s.Principal).includes('cloudfront.amazonaws.com'),
+    );
+    expect(oacGrant, 'expected a cloudfront OAC bucket-policy statement').toBeDefined();
+  });
+
+  it('scopes the OAC grant to this distribution via a StringEquals AWS:SourceArn condition', () => {
+    // OAC uses a condition keyed on `AWS:SourceArn` (the distribution ARN)
+    // so only THIS distribution can read the bucket, not every CloudFront
+    // distribution in the account.
+    const { template } = makeSiteTemplate();
+    const statements = bucketPolicyStatements(template);
+    const oacGrant = statements.find((s) =>
+      JSON.stringify(s.Principal).includes('cloudfront.amazonaws.com'),
+    );
+    const cond = JSON.stringify(oacGrant?.Condition ?? {});
+    expect(cond).toContain('StringEquals');
+    expect(cond).toContain('AWS:SourceArn');
+    expect(cond).toContain('cloudfront');
+    expect(cond).toContain('distribution');
+  });
+});
+
+describe('StaticSite — Origin Access Control (OAC)', () => {
+  it('creates an AWS::CloudFront::OriginAccessControl resource', () => {
+    const { template } = makeSiteTemplate();
+    template.resourceCountIs('AWS::CloudFront::OriginAccessControl', 1);
+  });
+
+  it('configures the OAC for an S3 origin with SIGV4_ALWAYS signing', () => {
+    const { template } = makeSiteTemplate();
+    const oacs = template.findResources('AWS::CloudFront::OriginAccessControl') as Record<
+      string,
+      {
+        Properties?: {
+          OriginAccessControlConfig?: {
+            OriginAccessControlOriginType?: string;
+            SigningProtocol?: string;
+            SigningBehavior?: string;
+          };
+        };
+      }
+    >;
+    const oac = Object.values(oacs)[0]?.Properties?.OriginAccessControlConfig;
+    expect(oac?.OriginAccessControlOriginType).toBe('s3');
+    expect(oac?.SigningProtocol).toBe('sigv4');
+    expect(oac?.SigningBehavior).toBe('always');
+  });
+
+  it('references the OAC id from the S3 origin', () => {
+    const { template } = makeSiteTemplate();
+    const origin = distConfig(template).Origins?.[0];
+    expect(origin?.OriginAccessControlId).toBeDefined();
+  });
+});
+
+describe('StaticSite — default root object + SPA error response', () => {
+  it('serves the landing page (/index.html) as the default root object', () => {
+    // `https://<dist>/` must serve the project landing page (the 13 KB
+    // static HTML at `dist/index.html` produced by step 5 of
+    // `apps/web/scripts/build.mjs`). Without this `defaultRootObject`,
+    // a request to `/` would 403 against the private bucket and trigger
+    // the SPA error response, which is the wrong page (the SPA shell,
+    // not the landing page).
+    const { template } = makeSiteTemplate();
+    const dists = template.findResources('AWS::CloudFront::Distribution') as Record<
+      string,
+      { Properties?: { DistributionConfig?: { DefaultRootObject?: string } } }
+    >;
+    const root = Object.values(dists)[0]?.Properties?.DistributionConfig?.DefaultRootObject;
+    expect(root).toBe('index.html');
+  });
+
+  it('maps HTTP 403 → 200 with response page /webclient/index.html', () => {
+    const { template } = makeSiteTemplate();
+    const errors = distConfig(template).CustomErrorResponses ?? [];
+    const mapping = errors.find((e) => e.ErrorCode === 403);
+    expect(mapping, 'expected a 403 custom error response').toBeDefined();
+    expect(mapping?.ResponseCode).toBe(200);
+    expect(mapping?.ResponsePagePath).toBe('/webclient/index.html');
+  });
+
+  it('maps HTTP 404 → 200 with response page /webclient/index.html', () => {
+    const { template } = makeSiteTemplate();
+    const errors = distConfig(template).CustomErrorResponses ?? [];
+    const mapping = errors.find((e) => e.ErrorCode === 404);
+    expect(mapping, 'expected a 404 custom error response').toBeDefined();
+    expect(mapping?.ResponseCode).toBe(200);
+    expect(mapping?.ResponsePagePath).toBe('/webclient/index.html');
+  });
+});
+
+describe('StaticSite — WebsiteURL output', () => {
+  /**
+   * The `WebsiteURL` CfnOutput lives inside the `StaticSite` construct, but
+   * its logical id is pinned to the stable key `WebsiteURL` via
+   * `overrideLogicalId` so operators see `Stack.WebsiteURL` rather than the
+   * CDK-hashed `StaticSiteWebsiteURL<8-hex>`. This matches the convention
+   * used by the parent-stack outputs (`WebsiteBucketName`,
+   * `WebsiteDistributionId`) and keeps the deploy pipeline's
+   * `describe-stacks --query` lookups predictable.
+   */
+  it('emits a WebsiteURL output with a stable logical id (no CDK hash) naming the distribution domain', () => {
+    const { template } = makeSiteTemplate();
+    const outputs = (template.toJSON().Outputs ?? {}) as Record<string, { Value?: unknown }>;
+    expect(outputs.WebsiteURL, 'expected a WebsiteURL output with a stable key').toBeDefined();
+    const distIds = Object.keys(template.findResources('AWS::CloudFront::Distribution'));
+    expect(distIds).toHaveLength(1);
+    const getAtt = (outputs.WebsiteURL?.Value as { 'Fn::GetAtt'?: unknown[] })?.['Fn::GetAtt'];
+    expect(getAtt, 'expected WebsiteURL.Value to Fn::GetAtt the distribution DomainName').toEqual([
+      distIds[0],
+      'DomainName',
+    ]);
+  });
+});
+
+describe('StaticSite — default domain (no custom-domain props)', () => {
+  it('does NOT configure an alternate domain name when no custom domain is provided', () => {
+    const { template } = makeSiteTemplate();
+    expect(distConfig(template).Aliases).toBeUndefined();
+  });
+
+  it('does NOT create a Route53 record when no custom domain is provided', () => {
+    const { template } = makeSiteTemplate();
+    template.resourceCountIs('AWS::Route53::RecordSet', 0);
+  });
+});
+
+describe('StaticSite — custom domain (opt-in)', () => {
+  const customProps: StaticSiteProps = {
+    customDomain: 'app.example.com',
+    certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc',
+    hostedZoneName: 'example.com.',
+    hostedZoneId: 'Z2KVMGOMG3KSP5',
+  };
+
+  it('configures the alternate domain name on the distribution', () => {
+    const { template } = makeSiteTemplate(customProps);
+    expect(distConfig(template).Aliases).toEqual(['app.example.com']);
+  });
+
+  it('attaches the provided ACM certificate as the viewer certificate', () => {
+    const { template } = makeSiteTemplate(customProps);
+    const dists = template.findResources('AWS::CloudFront::Distribution') as Record<
+      string,
+      {
+        Properties?: {
+          DistributionConfig?: { ViewerCertificate?: { AcmCertificateArn?: string } };
+        };
+      }
+    >;
+    const cert =
+      Object.values(dists)[0]?.Properties?.DistributionConfig?.ViewerCertificate?.AcmCertificateArn;
+    expect(cert).toBe('arn:aws:acm:us-east-1:123456789012:certificate/abc');
+  });
+
+  it('creates a Route53 ARecord aliasing the distribution', () => {
+    const { template } = makeSiteTemplate(customProps);
+    template.hasResourceProperties('AWS::Route53::RecordSet', {
+      Name: 'app.example.com.',
+      Type: 'A',
+    });
+  });
+
+  it('configures the alias without a viewer certificate when certificateArn is omitted', () => {
+    // CloudFront requires a cert for an alias at deploy time, but the
+    // construct does not fail at synth when none is imported — the deploy
+    // surfaces the CFN error. This exercises the no-cert branch so the
+    // synth path is covered either way.
+    const { template } = makeSiteTemplate({
+      customDomain: 'app.example.com',
+      hostedZoneName: 'example.com.',
+      hostedZoneId: 'Z2KVMGOMG3KSP5',
+    });
+    expect(distConfig(template).Aliases).toEqual(['app.example.com']);
+    const dists = template.findResources('AWS::CloudFront::Distribution') as Record<
+      string,
+      { Properties?: { DistributionConfig?: { ViewerCertificate?: unknown } } }
+    >;
+    expect(
+      Object.values(dists)[0]?.Properties?.DistributionConfig?.ViewerCertificate,
+    ).toBeUndefined();
+  });
+
+  it('skips the Route53 record when the hosted zone id is omitted', () => {
+    // The ARecord needs both zone name AND id (fromHostedZoneAttributes);
+    // without the id the alias is still configured on the distribution but
+    // no Route53 record is materialised.
+    const { template } = makeSiteTemplate({
+      customDomain: 'app.example.com',
+      certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc',
+      hostedZoneName: 'example.com.',
+    });
+    expect(distConfig(template).Aliases).toEqual(['app.example.com']);
+    template.resourceCountIs('AWS::Route53::RecordSet', 0);
+  });
+
+  it('skips the Route53 record when hostedZoneName is omitted', () => {
+    const { template } = makeSiteTemplate({
+      customDomain: 'app.example.com',
+      certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abc',
+    });
+    template.resourceCountIs('AWS::Route53::RecordSet', 0);
+  });
+});
+
+describe('StaticSite — directory-index viewer-request function', () => {
+  // S3 REST origins (used with OAC) do NOT resolve directory indexes: a
+  // request for '/docs/' looks up an object literally named 'docs/' and
+  // 404s, which then falls through to the SPA error response and serves
+  // Kiwi instead of the rendered docs index (reproduced live on
+  // irc.aws.fowl.cloud). A CloudFront viewer-request function appends
+  // 'index.html' to any URI ending in '/', mirroring the CF Worker
+  // `[assets]` binding which resolves directory indexes automatically.
+
+  it('creates exactly one AWS::CloudFront::Function', () => {
+    const { template } = makeSiteTemplate();
+    template.resourceCountIs('AWS::CloudFront::Function', 1);
+  });
+
+  it('associates the function as a viewer-request on the default behavior', () => {
+    const { template } = makeSiteTemplate();
+    const associations = distConfig(template).DefaultCacheBehavior?.FunctionAssociations ?? [];
+    const viewerRequest = associations.find((a) => a.EventType === 'viewer-request');
+    expect(viewerRequest, 'expected a viewer-request function association').toBeDefined();
+  });
+
+  it('rewrites a trailing-slash directory URI by appending index.html', () => {
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    expect(handler({ request: { uri: '/docs/' } }).uri).toBe('/docs/index.html');
+  });
+
+  it('301-redirects a directory URI without a trailing slash to the trailing-slash form', () => {
+    // A bare '/docs' must NOT be internally rewritten to '/docs/index.html':
+    // the browser URL would stay at '/docs' and the page's relative asset
+    // links (e.g. <link href="docs.css">) would resolve against the parent
+    // ('/docs.css') instead of the directory ('/docs/docs.css'). A 301 to
+    // '/docs/' makes the browser re-request the directory form, after which
+    // the trailing-slash rewrite serves '/docs/index.html' and relative
+    // links resolve correctly. Mirrors Apache/nginx DirectorySlash.
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    const result = handler({ request: { uri: '/docs' } });
+    expect(result.statusCode).toBe(301);
+    expect(result.headers?.location?.value).toBe('/docs/');
+  });
+
+  it('preserves the query string in the no-trailing-slash redirect', () => {
+    // CloudFront Functions deliver request.querystring as an OBJECT
+    // ({ key: { value: "..." } }), not a raw string — an empty querystring
+    // is {} (truthy), so a naive string concat would append "?[object
+    // Object]". The function rebuilds the query string from the object.
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    const result = handler({
+      request: { uri: '/docs', querystring: { foo: { value: 'bar' } } },
+    });
+    expect(result.statusCode).toBe(301);
+    expect(result.headers?.location?.value).toBe('/docs/?foo=bar');
+  });
+
+  it('omits the query string entirely when there are no params', () => {
+    // Regression guard for the live "?[object Object]" bug: an empty
+    // querystring object must NOT append a trailing "?".
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    const result = handler({ request: { uri: '/docs', querystring: {} } });
+    expect(result.statusCode).toBe(301);
+    expect(result.headers?.location?.value).toBe('/docs/');
+  });
+
+  it('rewrites the bare root "/" to "/index.html"', () => {
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    expect(handler({ request: { uri: '/' } }).uri).toBe('/index.html');
+  });
+
+  it('leaves a URI with a file extension unchanged', () => {
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    expect(handler({ request: { uri: '/docs/Services.html' } }).uri).toBe('/docs/Services.html');
+  });
+
+  it('leaves a hashed asset path unchanged', () => {
+    // Every real static asset carries a file extension (.js/.css/.png/
+    // .json/.woff2/.ico), so the no-extension rewrite never touches them.
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    expect(handler({ request: { uri: '/webclient/static/js/app.d5acc7fe.js' } }).uri).toBe(
+      '/webclient/static/js/app.d5acc7fe.js',
+    );
+  });
+
+  it('301-redirects a no-extension SPA deep-link to the trailing-slash form', () => {
+    // A SPA client-side route like '/webclient/networks/example' has no
+    // extension, so the function redirects it to the trailing-slash form
+    // '/webclient/networks/example/'. That object does not exist → S3 404
+    // → the 403/404 SPA error response still serves '/webclient/index.html'
+    // (unchanged), and Kiwi's router resolves the deep link from the URL.
+    // The redirect therefore does not break SPA routing; it merely routes
+    // the (expected) miss through the existing fallback, with a canonical
+    // trailing slash on the browser URL.
+    const { template } = makeSiteTemplate();
+    const handler = extractIndexHandler(template);
+    const result = handler({ request: { uri: '/webclient/networks/example' } });
+    expect(result.statusCode).toBe(301);
+    expect(result.headers?.location?.value).toBe('/webclient/networks/example/');
+  });
+});

package/apps/aws-stack/tests/synth-no-bundle.test.ts

@@ -57,7 +57,6 @@ describe('IrcAwsStack — test-mode bundle stub (no esbuild)', () => {
   it('emits inline (ZipFile) Lambda code for the NLB streaming handler when tcpTlsDomainName is set', () => {
     const app = new App();
     const stack = new IrcAwsStack(app, 'TestStack', {
-      environmentName: 'staging',
       tcpTlsDomainName: 'irc.example.com',
     });
     const template = Template.fromStack(stack);

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.9.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,8 +10,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "start": "node --enable-source-maps ./dist/main.js",
-    "deploy:staging": "wrangler deploy --env staging",
-    "deploy:prod": "wrangler deploy",
+    "deploy": "node ../../tools/ci-hardening/dist/cf-deploy-cli.js wrangler.toml",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
@@ -22,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",