serverless-ircd 0.8.0 → 0.10.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-tcp-container",
-  "version": "0.8.0",
+  "version": "0.10.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": "wrangler deploy",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",

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

@@ -18,20 +18,21 @@ import { randomUUID } from 'node:crypto';
 import { type Server, type Socket, createServer } from 'node:net';
 import { InMemoryRuntime } from '@serverless-ircd/in-memory-runtime';
 import {
-  type AccountStore,
   type AdmissionConfig,
   type ChanName,
   type Clock,
   type ConnectionState,
   ConsoleLogger,
-  InMemoryAccountStore,
   InMemoryMessageStore,
   InMemoryNickHistoryStore,
+  InMemoryServicesStore,
   LogLevel,
   type Logger,
   type MessageStore,
   type NickHistoryStore,
   type RawLine,
+  type ServicesStore,
+  SystemClock,
   createConnection,
 } from '@serverless-ircd/irc-core';
 import { ConnectionActor, TcpByteStreamTransport } from '@serverless-ircd/irc-server';
@@ -95,6 +96,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(),
 };
@@ -131,10 +135,12 @@ export async function startContainerServer(opts: StartContainerOptions): Promise
 
   const messages = new InMemoryMessageStore(opts.historyMaxPerChannel);
   const history = new InMemoryNickHistoryStore(clock);
-  const accounts: AccountStore | undefined =
-    opts.saslAccounts !== undefined && opts.saslAccounts.length > 0
-      ? new InMemoryAccountStore(opts.saslAccounts)
-      : undefined;
+  // Services store: the single credential home. Seeded from `saslAccounts`
+  // so SASL PLAIN / PASS-auth / NickServ IDENTIFY all verify.
+  const services = new InMemoryServicesStore({ clock: SystemClock });
+  for (const acct of opts.saslAccounts ?? []) {
+    services.registerNick(acct.username, acct.password, '');
+  }
 
   // Restore persisted channel state before accepting connections.
   if (opts.persistencePath !== undefined) {
@@ -154,12 +160,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;
@@ -167,7 +182,7 @@ export async function startContainerServer(opts: StartContainerOptions): Promise
     const admissionRecordId = decision.recordId;
     runtime.commitAdmission(ip, undefined, admissionRecordId);
 
-    const { state, actor } = attachConnection(runtime, opts, messages, accounts, history, clock, {
+    const { state, actor } = attachConnection(runtime, opts, messages, services, history, clock, {
       sendText: (text) => {
         if (socket.writable) socket.write(text);
       },
@@ -213,8 +228,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,
@@ -243,7 +262,7 @@ function attachConnection(
   runtime: InMemoryRuntime,
   opts: StartContainerOptions,
   messages: MessageStore,
-  accounts: AccountStore | undefined,
+  services: ServicesStore,
   history: NickHistoryStore,
   clock: Clock,
   transport: {
@@ -255,9 +274,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);
 
@@ -282,7 +305,7 @@ function attachConnection(
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => opts.motdLines ?? [] },
     messages,
-    ...(accounts !== undefined ? { accounts } : {}),
+    ...(services !== undefined ? { services } : {}),
     history,
     logger,
     transport: new TcpByteStreamTransport(),