serverless-ircd 0.7.0 → 0.9.0

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

@@ -3,7 +3,7 @@
  *
  * These are the primary red→green tests for the infrastructure stack:
  * they assert the exact CloudFormation shape that `cdk synth` must
- * produce — five DynamoDB tables with the PLAN §4 schema, a single
+ * produce — six DynamoDB tables with the PLAN §4 schema, a single
  * Node 24 Lambda wired to all three WebSocket routes, the API Gateway
  * v2 WebSocket API, the two stack outputs, and a least-privilege guard
  * that no IAM policy grants `Resource: '*'` or `Action: '*'`.
@@ -44,10 +44,44 @@ function makeTemplate(environmentName?: string): { app: App; stack: Stack; templ
   return { app, stack, template };
 }
 
+/** Returns the synthesised CloudFormation `Parameters` section as a record. */
+function parameters(
+  template: Template,
+): Record<string, { Type: string; Default?: string; Description?: string }> {
+  const tmpl = template.toJSON() as {
+    Parameters?: Record<string, { Type: string; Default?: string; Description?: string }>;
+  };
+  return tmpl.Parameters ?? {};
+}
+
+/**
+ * Finds the `AWS::Events::Rule` whose target `Arn` references a Lambda
+ * with the given logical-id prefix (CDK appends a hash suffix, e.g.
+ * `IrcSweeper7D484D9E`). Match is via `Fn::GetAtt: [<id>, Arn]`.
+ */
+function findRuleTargetingLambda(
+  template: Template,
+  fnIdPrefix: string,
+):
+  | { Properties?: { ScheduleExpression?: unknown; Targets?: Array<{ Arn?: unknown }> } }
+  | undefined {
+  const rules = template.findResources('AWS::Events::Rule') as Record<
+    string,
+    { Properties?: { Targets?: Array<{ Arn?: unknown }> } }
+  >;
+  return Object.values(rules).find((rule) =>
+    (rule.Properties?.Targets ?? []).some((t) => {
+      const getAtt = (t.Arn as { 'Fn::GetAtt'?: string[] } | undefined)?.['Fn::GetAtt'];
+      const id = Array.isArray(getAtt) ? getAtt[0] : undefined;
+      return typeof id === 'string' && id.startsWith(fnIdPrefix);
+    }),
+  );
+}
+
 describe('IrcAwsStack — DynamoDB tables', () => {
-  it('creates exactly five DynamoDB tables', () => {
+  it('creates exactly six DynamoDB tables', () => {
     const { template } = makeTemplate();
-    template.resourceCountIs('AWS::DynamoDB::Table', 5);
+    template.resourceCountIs('AWS::DynamoDB::Table', 6);
   });
 
   it.each(TABLE_NAMES)('creates the %s table', (tableName) => {
@@ -125,6 +159,21 @@ describe('IrcAwsStack — DynamoDB tables', () => {
       KeySchema: [{ AttributeName: 'account', KeyType: 'HASH' }],
     });
   });
+
+  it('keys the Services table by composite pk/sk (String/String)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'Services'),
+      AttributeDefinitions: [
+        { AttributeName: 'pk', AttributeType: 'S' },
+        { AttributeName: 'sk', AttributeType: 'S' },
+      ],
+      KeySchema: [
+        { AttributeName: 'pk', KeyType: 'HASH' },
+        { AttributeName: 'sk', KeyType: 'RANGE' },
+      ],
+    });
+  });
 });
 
 describe('IrcAwsStack — API Gateway v2 WebSocket API', () => {
@@ -171,7 +220,7 @@ describe('IrcAwsStack — IRCv3 WebSocket subprotocol echo', () => {
     const { template } = makeTemplate();
     template.hasResourceProperties('AWS::ApiGatewayV2::IntegrationResponse', {
       ResponseParameters: {
-        'method.response.header.Sec-WebSocket-Protocol':
+        'route.response.header.Sec-WebSocket-Protocol':
           'integration.response.header.Sec-WebSocket-Protocol',
       },
     });
@@ -197,6 +246,163 @@ describe('IrcAwsStack — IRCv3 WebSocket subprotocol echo', () => {
   });
 });
 
+describe('IrcAwsStack — API Gateway logging', () => {
+  /** Returns the synthesised CloudFormation `Parameters` section. */
+  function parameters(
+    template: Template,
+  ): Record<
+    string,
+    { Type: string; Default?: string; AllowedValues?: string[]; Description?: string }
+  > {
+    const tmpl = template.toJSON() as {
+      Parameters?: Record<
+        string,
+        {
+          Type: string;
+          Default?: string;
+          AllowedValues?: string[];
+          Description?: string;
+        }
+      >;
+    };
+    return tmpl.Parameters ?? {};
+  }
+
+  it('exposes ApiGatewayLoggingLevel as a configurable String parameter (default INFO)', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).ApiGatewayLoggingLevel;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('String');
+    expect(p?.Default).toBe('INFO');
+    expect(typeof p?.Description).toBe('string');
+    expect(p?.Description?.length).toBeGreaterThan(0);
+  });
+
+  it('restricts ApiGatewayLoggingLevel to OFF/INFO/ERROR', () => {
+    const { template } = makeTemplate();
+    expect(parameters(template).ApiGatewayLoggingLevel?.AllowedValues).toEqual([
+      'OFF',
+      'INFO',
+      'ERROR',
+    ]);
+  });
+
+  it('wires the stage execution logging level to the parameter (Ref) with data tracing on', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::Stage', {
+      DefaultRouteSettings: {
+        LoggingLevel: { Ref: 'ApiGatewayLoggingLevel' },
+        DataTraceEnabled: true,
+      },
+    });
+  });
+
+  it('creates a CloudWatch LogGroup for API Gateway access logs', () => {
+    const { template } = makeTemplate();
+    template.resourceCountIs('AWS::Logs::LogGroup', 1);
+  });
+
+  it('configures the API Gateway account CloudWatch role so execution logs can be written', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGateway::Account', {});
+  });
+
+  it('wires the stage access log destination to the LogGroup', () => {
+    const { template } = makeTemplate();
+    const stages = template.findResources('AWS::ApiGatewayV2::Stage') as Record<
+      string,
+      { Properties?: { AccessLogSettings?: { DestinationArn?: unknown } } }
+    >;
+    const stage = Object.values(stages)[0];
+    expect(stage?.Properties?.AccessLogSettings?.DestinationArn).toBeDefined();
+  });
+
+  it('makes the stage depend on the account CloudWatch role so logging can enable', () => {
+    // Without an explicit DependsOn, CloudFormation may apply the Stage's
+    // logging config before the AWS::ApiGateway::Account resource sets the
+    // account-wide CloudWatch role, and APIGW rejects the update:
+    //   "CloudWatch Logs role ARN must be set in account settings to enable logging"
+    const { template } = makeTemplate();
+    const accountIds = Object.keys(template.findResources('AWS::ApiGateway::Account'));
+    expect(accountIds).toHaveLength(1);
+    const stages = template.findResources('AWS::ApiGatewayV2::Stage') as Record<
+      string,
+      { DependsOn?: string[] }
+    >;
+    const stage = Object.values(stages)[0];
+    expect(stage?.DependsOn).toBeDefined();
+    expect(stage?.DependsOn?.some((id) => accountIds.includes(id))).toBe(true);
+  });
+
+  it('makes the API Gateway Account depend on the logging role permissions policy', () => {
+    // APIGW validates the account CloudWatch role's CONTENT (trust AND the
+    // attached permissions) when it processes the AWS::ApiGateway::Account
+    // resource. CDK renders `addToPolicy` as a SEPARATE AWS::IAM::Policy
+    // resource, and the Account only references the role Arn, so without an
+    // explicit DependsOn CloudFormation can apply the Account after the Role
+    // is created but BEFORE the policy attaches. APIGW then assumes a
+    // permission-less role and rejects the update:
+    //   "The role ARN does not have required permissions configured."
+    const { template } = makeTemplate();
+    const accounts = template.findResources('AWS::ApiGateway::Account') as Record<
+      string,
+      { DependsOn?: string[] }
+    >;
+    expect(Object.keys(accounts)).toHaveLength(1);
+    const account = Object.values(accounts)[0];
+    expect(
+      account?.DependsOn,
+      'Account must depend on the logging role permissions policy',
+    ).toBeDefined();
+    const policyIds = new Set(Object.keys(template.findResources('AWS::IAM::Policy')));
+    expect(
+      account?.DependsOn?.some((id) => policyIds.has(id)),
+      `Account.DependsOn ${JSON.stringify(account?.DependsOn)} must include the logging role policy`,
+    ).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();
+    const roles = template.findResources('AWS::IAM::Role') as Record<string, unknown>;
+    const loggingRoleEntry = Object.entries(roles).find(([id]) =>
+      id.startsWith('ApiGatewayLoggingRole'),
+    );
+    expect(loggingRoleEntry, 'expected an ApiGatewayLoggingRole').toBeDefined();
+    const loggingRoleId = loggingRoleEntry?.[0];
+    const policies = template.findResources('AWS::IAM::Policy') as Record<
+      string,
+      {
+        Properties?: {
+          Roles?: Array<{ Ref?: string }>;
+          PolicyDocument?: {
+            Statement?: Array<{ Action?: string | string[]; Resource?: unknown }>;
+          };
+        };
+      }
+    >;
+    const attached = Object.values(policies).find((p) =>
+      (p.Properties?.Roles ?? []).some((r) => r.Ref === loggingRoleId),
+    );
+    expect(attached, 'expected an inline policy attached to the logging role').toBeDefined();
+    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('*');
+  });
+});
+
 describe('IrcAwsStack — Lambda', () => {
   it('creates exactly three Lambda functions (handler + sweeper + pingChecker)', () => {
     const { template } = makeTemplate();
@@ -212,18 +418,13 @@ describe('IrcAwsStack — Lambda', () => {
 });
 
 describe('IrcAwsStack — gone-connection sweeper', () => {
-  it('creates an EventBridge rule on a fixed schedule targeting the sweeper', () => {
+  it('creates an EventBridge rule targeting the sweeper Lambda', () => {
     const { template } = makeTemplate();
-    template.hasResourceProperties('AWS::Events::Rule', {
-      ScheduleExpression: 'rate(5 minutes)',
-    });
+    expect(findRuleTargetingLambda(template, 'IrcSweeper')).toBeDefined();
   });
 
-  it('wires the sweeper Lambda as an EventBridge target', () => {
+  it('grants EventBridge permission to invoke the sweeper', () => {
     const { template } = makeTemplate();
-    template.hasResourceProperties('AWS::Events::Rule', {
-      ScheduleExpression: 'rate(5 minutes)',
-    });
     // EventBridge needs permission to invoke each scheduled target. APIGW
     // also creates one permission per route ($connect/$disconnect/$default),
     // so the total is 5: 3 APIGW + 2 EventBridge (sweeper + pingChecker).
@@ -237,16 +438,14 @@ describe('IrcAwsStack — gone-connection sweeper', () => {
     // Both Lambda roles must scope their DynamoDB actions to the concrete
     // table ARNs — the least-privilege suite below also asserts no '*'.
     const tables = template.findResources('AWS::DynamoDB::Table');
-    expect(Object.keys(tables)).toHaveLength(5);
+    expect(Object.keys(tables)).toHaveLength(6);
   });
 });
 
 describe('IrcAwsStack — idle / PING checker', () => {
-  it('creates an EventBridge rule firing every 1 minute', () => {
+  it('creates an EventBridge rule targeting the pingChecker Lambda', () => {
     const { template } = makeTemplate();
-    template.hasResourceProperties('AWS::Events::Rule', {
-      ScheduleExpression: 'rate(1 minute)',
-    });
+    expect(findRuleTargetingLambda(template, 'IrcPingChecker')).toBeDefined();
   });
 
   it('creates exactly two EventBridge rules (sweeper + pingChecker)', () => {
@@ -294,6 +493,55 @@ describe('IrcAwsStack — idle / PING checker', () => {
   });
 });
 
+describe('IrcAwsStack — schedule CloudFormation parameters', () => {
+  it('exposes SweeperScheduleExpression and PingCheckerScheduleExpression as parameters', () => {
+    const { template } = makeTemplate();
+    const keys = Object.keys(parameters(template));
+    expect(keys).toContain('SweeperScheduleExpression');
+    expect(keys).toContain('PingCheckerScheduleExpression');
+  });
+
+  it('declares SweeperScheduleExpression as a String parameter with a non-empty description', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).SweeperScheduleExpression;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('String');
+    expect(typeof p?.Description).toBe('string');
+    expect(p?.Description?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  it('declares PingCheckerScheduleExpression as a String parameter with a non-empty description', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).PingCheckerScheduleExpression;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('String');
+    expect(typeof p?.Description).toBe('string');
+    expect(p?.Description?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  it('defaults SweeperScheduleExpression to rate(5 minutes) when the prop is omitted', () => {
+    const { template } = makeTemplate();
+    expect(parameters(template).SweeperScheduleExpression?.Default).toBe('rate(5 minutes)');
+  });
+
+  it('defaults PingCheckerScheduleExpression to rate(1 minute) when the prop is omitted', () => {
+    const { template } = makeTemplate();
+    expect(parameters(template).PingCheckerScheduleExpression?.Default).toBe('rate(1 minute)');
+  });
+
+  it('wires the sweeper rule ScheduleExpression via Ref to the parameter', () => {
+    const { template } = makeTemplate();
+    const rule = findRuleTargetingLambda(template, 'IrcSweeper');
+    expect(rule?.Properties?.ScheduleExpression).toEqual({ Ref: 'SweeperScheduleExpression' });
+  });
+
+  it('wires the pingChecker rule ScheduleExpression via Ref to the parameter', () => {
+    const { template } = makeTemplate();
+    const rule = findRuleTargetingLambda(template, 'IrcPingChecker');
+    expect(rule?.Properties?.ScheduleExpression).toEqual({ Ref: 'PingCheckerScheduleExpression' });
+  });
+});
+
 describe('IrcAwsStack — stack outputs', () => {
   it('emits a ConnectUrl output', () => {
     const { template } = makeTemplate();
@@ -333,10 +581,45 @@ describe('IrcAwsStack — least-privilege IAM', () => {
 
   it('never grants Resource: "*" in any IAM policy', () => {
     const { template } = makeTemplate();
+    // Documented exception: the API Gateway account CloudWatch role MUST
+    // use Resource: '*'. APIGW writes execution logs to its OWN
+    // AWS/ApiGateway... log groups (not this stack's access-log group), and
+    // rejects a role scoped to a single log-group ARN. Identify the role's
+    // policy by the apigateway service principal so the exception is narrow.
+    const apigwRoleIds = new Set(
+      Object.entries(template.findResources('AWS::IAM::Role'))
+        .filter(([, r]) => {
+          const stmts =
+            (
+              r as {
+                Properties?: {
+                  AssumeRolePolicyDocument?: {
+                    Statement?: Array<{ Principal?: { Service?: string } }>;
+                  };
+                };
+              }
+            ).Properties?.AssumeRolePolicyDocument?.Statement ?? [];
+          return stmts.some((s) => s.Principal?.Service === 'apigateway.amazonaws.com');
+        })
+        .map(([id]) => id),
+    );
     const policies = template.findResources('AWS::IAM::Policy');
     for (const [, policy] of Object.entries(policies)) {
-      const statements = (policy as { Properties: { PolicyDocument: { Statement: unknown[] } } })
-        .Properties.PolicyDocument.Statement;
+      const props = (
+        policy as {
+          Properties: {
+            Roles?: Array<{ Ref?: string }>;
+            PolicyDocument: { Statement: unknown[] };
+          };
+        }
+      ).Properties;
+      const isApigwLoggingPolicy = (props.Roles ?? []).some(
+        (r) => r.Ref !== undefined && apigwRoleIds.has(r.Ref),
+      );
+      if (isApigwLoggingPolicy) {
+        continue;
+      }
+      const statements = props.PolicyDocument.Statement;
       for (const stmt of statements) {
         const resource = (stmt as { Resource?: unknown }).Resource;
         if (Array.isArray(resource)) {
@@ -410,8 +693,8 @@ describe('IrcAwsStack — environmentName prop (env isolation)', () => {
         { Properties: { TableName: string } }
       >,
     ).map((t) => t.Properties.TableName);
-    expect(stagingTables).toHaveLength(5);
-    expect(prodTables).toHaveLength(5);
+    expect(stagingTables).toHaveLength(6);
+    expect(prodTables).toHaveLength(6);
     expect(prodNames.every((n) => !stagingNames.has(n))).toBe(true);
   });
 
@@ -424,17 +707,17 @@ describe('IrcAwsStack — environmentName prop (env isolation)', () => {
   });
 });
 
-describe('IrcAwsStack — server identity props (configurable deploy identity)', () => {
+describe('IrcAwsStack — server identity CloudFormation parameters', () => {
   /** Finds a Lambda function resource by its logical-id prefix (e.g. `IrcHandler`). */
   function findFunction(
     template: Template,
     idPrefix: string,
   ): {
-    Properties?: { Environment?: { Variables?: Record<string, string> } };
+    Properties?: { Environment?: { Variables?: Record<string, unknown> } };
   } {
     const fns = template.findResources('AWS::Lambda::Function') as Record<
       string,
-      { Properties?: { Environment?: { Variables?: Record<string, string> } } }
+      { Properties?: { Environment?: { Variables?: Record<string, unknown> } } }
     >;
     const found = Object.entries(fns).find(([id]) => id.startsWith(idPrefix));
     if (!found) {
@@ -443,70 +726,131 @@ describe('IrcAwsStack — server identity props (configurable deploy identity)',
     return found[1];
   }
 
-  it('injects an overridden serverName into the handler Lambda env', () => {
+  it('exposes ServerName and NetworkName as CloudFormation parameters', () => {
+    const { template } = makeTemplate();
+    const keys = Object.keys(parameters(template));
+    expect(keys).toContain('ServerName');
+    expect(keys).toContain('NetworkName');
+  });
+
+  it('declares ServerName as a String parameter with a non-empty description', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).ServerName;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('String');
+    expect(typeof p?.Description).toBe('string');
+    expect(p?.Description?.length).toBeGreaterThan(0);
+  });
+
+  it('declares NetworkName as a String parameter with a non-empty description', () => {
+    const { template } = makeTemplate();
+    const p = parameters(template).NetworkName;
+    expect(p).toBeDefined();
+    expect(p?.Type).toBe('String');
+    expect(typeof p?.Description).toBe('string');
+    expect(p?.Description?.length).toBeGreaterThan(0);
+  });
+
+  it('defaults ServerName to the non-placeholder fallback when the prop is omitted', () => {
+    const { template } = makeTemplate();
+    expect(parameters(template).ServerName?.Default).toBe('irc.localhost');
+  });
+
+  it('defaults NetworkName to the non-placeholder fallback when the prop is omitted', () => {
+    const { template } = makeTemplate();
+    expect(parameters(template).NetworkName?.Default).toBe('ExampleNet');
+  });
+
+  it('flows an overridden serverName prop into the parameter Default', () => {
     const app = new App();
     const stack = new IrcAwsStack(app, 'TestStack', { serverName: 'irc.my.net' });
     const template = Template.fromStack(stack);
-    expect(
-      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.SERVER_NAME,
-    ).toBe('irc.my.net');
+    expect(parameters(template).ServerName?.Default).toBe('irc.my.net');
   });
 
-  it('flows the overridden serverName into the pingChecker Lambda env', () => {
+  it('flows an overridden networkName prop into the parameter Default', () => {
     const app = new App();
-    const stack = new IrcAwsStack(app, 'TestStack', { serverName: 'irc.my.net' });
+    const stack = new IrcAwsStack(app, 'TestStack', { networkName: 'MyNet' });
     const template = Template.fromStack(stack);
-    // Catches the previously duplicated hard-coded copy on IrcPingChecker.
+    expect(parameters(template).NetworkName?.Default).toBe('MyNet');
+  });
+
+  it('wires SERVER_NAME on the handler Lambda via Ref to the parameter', () => {
+    const { template } = makeTemplate();
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.SERVER_NAME,
+    ).toEqual({ Ref: 'ServerName' });
+  });
+
+  it('wires SERVER_NAME on the pingChecker Lambda via Ref to the parameter', () => {
+    const { template } = makeTemplate();
     expect(
       findFunction(template, 'IrcPingChecker').Properties?.Environment?.Variables?.SERVER_NAME,
-    ).toBe('irc.my.net');
+    ).toEqual({ Ref: 'ServerName' });
   });
 
-  it('injects an overridden networkName into both handler and pingChecker', () => {
-    const app = new App();
-    const stack = new IrcAwsStack(app, 'TestStack', { networkName: 'MyNet' });
-    const template = Template.fromStack(stack);
+  it('wires NETWORK_NAME on the handler Lambda via Ref to the parameter', () => {
+    const { template } = makeTemplate();
     expect(
       findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.NETWORK_NAME,
-    ).toBe('MyNet');
+    ).toEqual({ Ref: 'NetworkName' });
+  });
+
+  it('wires NETWORK_NAME on the pingChecker Lambda via Ref to the parameter', () => {
+    const { template } = makeTemplate();
     expect(
       findFunction(template, 'IrcPingChecker').Properties?.Environment?.Variables?.NETWORK_NAME,
-    ).toBe('MyNet');
+    ).toEqual({ Ref: 'NetworkName' });
   });
 
-  it('joins motdLines with newline so the config loader splits them into separate lines', () => {
+  it('wires SERVER_NAME and NETWORK_NAME on the NLB handler via Ref when tcpTlsDomainName is set', () => {
     const app = new App();
-    const stack = new IrcAwsStack(app, 'TestStack', { motdLines: ['line one', 'line two'] });
+    const stack = new IrcAwsStack(app, 'TestStack', { tcpTlsDomainName: 'irc.example.com' });
     const template = Template.fromStack(stack);
-    expect(findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.MOTD).toBe(
-      'line one\nline two',
-    );
+    expect(
+      findFunction(template, 'IrcNlbHandler').Properties?.Environment?.Variables?.SERVER_NAME,
+    ).toEqual({ Ref: 'ServerName' });
+    expect(
+      findFunction(template, 'IrcNlbHandler').Properties?.Environment?.Variables?.NETWORK_NAME,
+    ).toEqual({ Ref: 'NetworkName' });
   });
 
-  it('applies a non-placeholder fallback server identity when the props are omitted', () => {
+  it('injects server identity into the sweeper Lambda (shared config loader requires it)', () => {
+    // sweeperHandler calls buildDepsFromEnv() -> loadServerConfigFromLambdaEnv(),
+    // which hard-requires SERVER_NAME / NETWORK_NAME (and reads MOTD). Omitting
+    // them makes every scheduled sweeper invocation throw "serverName: Required"
+    // — so the sweeper MUST receive the same server-identity env vars as the
+    // handler, wired through the same CloudFormation parameters.
     const { template } = makeTemplate();
     expect(
-      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.SERVER_NAME,
-    ).toBe('irc.localhost');
+      findFunction(template, 'IrcSweeper').Properties?.Environment?.Variables?.SERVER_NAME,
+    ).toEqual({ Ref: 'ServerName' });
     expect(
-      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.NETWORK_NAME,
-    ).toBe('ExampleNet');
+      findFunction(template, 'IrcSweeper').Properties?.Environment?.Variables?.NETWORK_NAME,
+    ).toEqual({ Ref: 'NetworkName' });
+    expect(
+      findFunction(template, 'IrcSweeper').Properties?.Environment?.Variables?.MOTD,
+    ).toBeDefined();
+  });
+
+  it('joins motdLines with newline so the config loader splits them into separate lines', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { motdLines: ['line one', 'line two'] });
+    const template = Template.fromStack(stack);
+    expect(findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.MOTD).toBe(
+      'line one\nline two',
+    );
   });
 
   it('default MOTD is newline-joined so the loader yields multiple lines (no comma)', () => {
     const { template } = makeTemplate();
     const motd =
-      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.MOTD ?? '';
+      (findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.MOTD as
+        | string
+        | undefined) ?? '';
     expect(motd.split('\n').length).toBeGreaterThanOrEqual(2);
     expect(motd).not.toContain(',');
   });
-
-  it('does not inject server identity into the sweeper Lambda', () => {
-    const { template } = makeTemplate();
-    expect(
-      findFunction(template, 'IrcSweeper').Properties?.Environment?.Variables?.SERVER_NAME,
-    ).toBeUndefined();
-  });
 });
 
 describe('IrcAwsStack — TCP+TLS NLB adapter', () => {

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

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-tcp-container",
-  "version": "0.7.0",
+  "version": "0.9.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",

package/apps/cf-tcp-container/src/container-server.ts

@@ -95,6 +95,9 @@ interface ConnectionBindings {
 const DEFAULT_ID_FACTORY = {
   batchId: () => randomUUID(),
   nonce: () => randomUUID(),
+  // `sessionId` is required for `IdFactory` interface completeness; no
+  // current code path invokes it (only batchId/nonce/traceId are called).
+  // c8 ignore next 1
   sessionId: () => randomUUID(),
   traceId: () => randomUUID(),
 };
@@ -154,12 +157,21 @@ export async function startContainerServer(opts: StartContainerOptions): Promise
   const tcpServer = createServer((socket) => {
     sockets.add(socket);
 
+    // `remoteAddress` is always set on a TCP server's connection socket;
+    // the 'unknown' fallback is defensive and unreachable in practice.
+    /* c8 ignore start */
     const ip = socket.remoteAddress ?? 'unknown';
+    /* c8 ignore stop */
     const decision = runtime.admitConnection(ip, undefined);
     if (!decision.ok) {
+      // A freshly-accepted TCP socket is always writable; the else branch
+      // (skip the ERROR write) is a defensive guard against an impossible
+      // race and cannot be exercised over a real socket.
+      /* c8 ignore start */
       if (socket.writable) {
         socket.write(`ERROR :Closing link: (connection limit reached: ${decision.reason})\r\n`);
       }
+      /* c8 ignore stop */
       socket.destroy();
       sockets.delete(socket);
       return;
@@ -213,8 +225,12 @@ export async function startContainerServer(opts: StartContainerOptions): Promise
     const onListening = (): void => {
       tcpServer.removeListener('error', onError);
       const addr = tcpServer.address();
-      // c8 ignore next 1
+      // Inside the 'listening' handler `address()` is always an AddressInfo
+      // (TCP server, just bound); the null/string returns only occur for IPC
+      // sockets or before listening. The `opts.port` fallback is unreachable.
+      /* c8 ignore start */
       const port = typeof addr === 'object' && addr !== null ? addr.port : opts.port;
+      /* c8 ignore stop */
       resolve({
         port,
         host,
@@ -255,9 +271,13 @@ function attachConnection(
 ): ConnectionBindings {
   const id = randomUUID();
   const state = createConnection({ id, connectedSince: clock.now() });
+  // `transport.sourceHost` is always supplied (set to the peer IP) by the
+  // only call site above; the else branch is defensive and unreachable.
+  /* c8 ignore start */
   if (transport.sourceHost !== undefined) {
     state.host = transport.sourceHost;
   }
+  /* c8 ignore stop */
 
   const logger: Logger = new ConsoleLogger({ connectionId: id }, undefined, LogLevel.Info);