@opengroundplan/core 0.1.1

package/templates/layers/audit-log/files/src/audit/sinks.ts

@@ -0,0 +1,131 @@
+/**
+ * The append-only sink seam plus its three implementations. The port has no update and no
+ * delete on purpose — a sink that cannot rewrite history is the cheapest way to guarantee it.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalize } from './redact.js';
+import type { AuditRecord } from './event.js';
+import type { AuditSettings } from './settings.js';
+
+export interface AuditSink {
+  append(record: AuditRecord): Promise<void>;
+  /** Last stored record, so a restarted process continues the same chain. */
+  last(): Promise<AuditRecord | undefined>;
+  /** Whole trail in write order. Throws on sinks that cannot read their own output. */
+  readAll(): Promise<AuditRecord[]>;
+  close(): Promise<void>;
+}
+
+export class AuditSinkError extends Error {}
+
+/** Newline-delimited JSON: one record per line, appended, never rewritten. */
+export class FileAuditSink implements AuditSink {
+  private readonly filePath: string;
+  private directoryReady = false;
+
+  constructor(settings: AuditSettings) {
+    this.filePath = path.resolve(settings.filePath);
+  }
+
+  async append(record: AuditRecord): Promise<void> {
+    if (!this.directoryReady) {
+      await mkdir(path.dirname(this.filePath), { recursive: true });
+      this.directoryReady = true;
+    }
+    // 'a' is atomic for writes below PIPE_BUF on POSIX, so concurrent appends stay line-clean.
+    await appendFile(this.filePath, `${canonicalize(record)}\n`, { encoding: 'utf8', flag: 'a' });
+  }
+
+  async last(): Promise<AuditRecord | undefined> {
+    const records = await this.readAll();
+    return records.at(-1);
+  }
+
+  async readAll(): Promise<AuditRecord[]> {
+    let raw: string;
+    try {
+      raw = await readFile(this.filePath, 'utf8');
+    } catch (error) {
+      // An absent trail is an empty trail, not a failure — first run must not crash.
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    }
+    return raw
+      .split('\n')
+      .filter((line) => line.trim() !== '')
+      .map((line, index) => {
+        try {
+          return JSON.parse(line) as AuditRecord;
+        } catch {
+          throw new AuditSinkError(`audit: line ${index + 1} of ${this.filePath} is not valid JSON`);
+        }
+      });
+  }
+
+  async close(): Promise<void> {
+    this.directoryReady = false;
+  }
+}
+
+/** For a collector that already owns durability. Not readable back, so not verifiable in-process. */
+export class StdoutAuditSink implements AuditSink {
+  private lastRecord: AuditRecord | undefined;
+
+  async append(record: AuditRecord): Promise<void> {
+    process.stdout.write(`${canonicalize(record)}\n`);
+    this.lastRecord = record;
+  }
+
+  async last(): Promise<AuditRecord | undefined> {
+    return this.lastRecord;
+  }
+
+  async readAll(): Promise<AuditRecord[]> {
+    throw new AuditSinkError('audit: the stdout sink cannot read its own output — verify at the collector');
+  }
+
+  async close(): Promise<void> {
+    this.lastRecord = undefined;
+  }
+}
+
+/** Tests and dry runs. Bounded, because an unbounded array behind a write API is a leak. */
+export class MemoryAuditSink implements AuditSink {
+  private readonly records: AuditRecord[] = [];
+  private readonly limit: number;
+
+  constructor(settings: AuditSettings) {
+    this.limit = settings.maxMemoryEvents;
+  }
+
+  async append(record: AuditRecord): Promise<void> {
+    if (this.records.length >= this.limit) {
+      throw new AuditSinkError(`audit: in-memory sink is full at ${this.limit} records`);
+    }
+    this.records.push(record);
+  }
+
+  async last(): Promise<AuditRecord | undefined> {
+    return this.records.at(-1);
+  }
+
+  async readAll(): Promise<AuditRecord[]> {
+    return [...this.records];
+  }
+
+  async close(): Promise<void> {
+    this.records.length = 0;
+  }
+}
+
+export function createSink(settings: AuditSettings): AuditSink {
+  switch (settings.sink) {
+    case 'file':
+      return new FileAuditSink(settings);
+    case 'stdout':
+      return new StdoutAuditSink();
+    case 'memory':
+      return new MemoryAuditSink(settings);
+  }
+}

package/templates/layers/audit-log/files/src/audit/tests/audit.spec.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import { verifyChain } from '../chain.js';
+import { AuditEventError } from '../event.js';
+import { canonicalize } from '../redact.js';
+import { AuditRecorder } from '../recorder.js';
+import { MemoryAuditSink } from '../sinks.js';
+import { loadAuditSettings } from '../settings.js';
+import type { AuditRecord } from '../event.js';
+import type { AuditSettings } from '../settings.js';
+
+const PREFIX = '{{ auditEnvPrefix }}';
+
+function settings(overrides: Record<string, string> = {}): AuditSettings {
+  return loadAuditSettings({ [`${PREFIX}_SINK`]: 'memory', ...overrides });
+}
+
+async function trail(count: number): Promise<{ records: AuditRecord[]; settings: AuditSettings }> {
+  const config = settings();
+  const sink = new MemoryAuditSink(config);
+  const recorder = new AuditRecorder(config, sink);
+  for (let i = 1; i <= count; i += 1) {
+    await recorder.record({
+      action: 'invoice.approved',
+      outcome: 'success',
+      actorId: `user-${i}`,
+      resourceType: 'invoice',
+      resourceId: String(i),
+    });
+  }
+  return { records: await sink.readAll(), settings: config };
+}
+
+describe('audit chain', () => {
+  it('assigns contiguous sequence numbers and verifies clean', async () => {
+    const { records, settings: config } = await trail(3);
+    expect(records.map((r) => r.sequence)).toEqual([1, 2, 3]);
+    expect(verifyChain(records, config).valid).toBe(true);
+  });
+
+  it('detects an edited record', async () => {
+    const { records, settings: config } = await trail(3);
+    records[1].action = 'invoice.deleted';
+    const result = verifyChain(records, config);
+    expect(result.valid).toBe(false);
+    expect(result.breaks.some((b) => b.reason === 'hash-mismatch' && b.sequence === 2)).toBe(true);
+  });
+
+  it('detects a removed record', async () => {
+    const { records, settings: config } = await trail(3);
+    const result = verifyChain([records[0], records[2]], config);
+    expect(result.valid).toBe(false);
+    expect(result.breaks.some((b) => b.reason === 'sequence-gap')).toBe(true);
+    expect(result.breaks.some((b) => b.reason === 'broken-link')).toBe(true);
+  });
+
+  it('continues the chain after a restart', async () => {
+    const config = settings();
+    const sink = new MemoryAuditSink(config);
+    await new AuditRecorder(config, sink).record({ action: 'a', outcome: 'success', actorId: 'system' });
+    await new AuditRecorder(config, sink).record({ action: 'b', outcome: 'success', actorId: 'system' });
+    expect(verifyChain(await sink.readAll(), config).valid).toBe(true);
+  });
+});
+
+describe('audit redaction', () => {
+  it('replaces configured fields at any depth before writing', async () => {
+    const config = settings();
+    const sink = new MemoryAuditSink(config);
+    await new AuditRecorder(config, sink).record({
+      action: 'user.login',
+      outcome: 'failure',
+      actorId: 'user-1',
+      metadata: { attempt: 2, credentials: { password: 'hunter2', Token: 'abc' } },
+    });
+    const [record] = await sink.readAll();
+    const credentials = record.metadata.credentials as Record<string, unknown>;
+    expect(credentials.password).toBe(config.redactPlaceholder);
+    expect(credentials.Token).toBe(config.redactPlaceholder);
+    expect(record.metadata.attempt).toBe(2);
+  });
+});
+
+describe('audit event validation', () => {
+  it('rejects an event without an actor', async () => {
+    const config = settings();
+    const recorder = new AuditRecorder(config, new MemoryAuditSink(config));
+    await expect(recorder.record({ action: 'x', outcome: 'success', actorId: '' })).rejects.toThrow(
+      AuditEventError,
+    );
+  });
+});
+
+describe('canonical serialization', () => {
+  it('is independent of key insertion order', () => {
+    expect(canonicalize({ b: 1, a: { d: 2, c: 3 } })).toBe(canonicalize({ a: { c: 3, d: 2 }, b: 1 }));
+  });
+});

package/templates/layers/audit-log/files/src/audit/tests/audit.test.ts

@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+import { verifyChain } from '../chain.js';
+import { AuditEventError } from '../event.js';
+import { canonicalize } from '../redact.js';
+import { AuditRecorder } from '../recorder.js';
+import { MemoryAuditSink } from '../sinks.js';
+import { loadAuditSettings } from '../settings.js';
+import type { AuditRecord } from '../event.js';
+import type { AuditSettings } from '../settings.js';
+
+const PREFIX = '{{ auditEnvPrefix }}';
+
+function settings(overrides: Record<string, string> = {}): AuditSettings {
+  return loadAuditSettings({ [`${PREFIX}_SINK`]: 'memory', ...overrides });
+}
+
+async function trail(count: number): Promise<{ records: AuditRecord[]; settings: AuditSettings }> {
+  const config = settings();
+  const sink = new MemoryAuditSink(config);
+  const recorder = new AuditRecorder(config, sink);
+  for (let i = 1; i <= count; i += 1) {
+    await recorder.record({
+      action: 'invoice.approved',
+      outcome: 'success',
+      actorId: `user-${i}`,
+      resourceType: 'invoice',
+      resourceId: String(i),
+    });
+  }
+  return { records: await sink.readAll(), settings: config };
+}
+
+describe('audit chain', () => {
+  it('assigns contiguous sequence numbers and verifies clean', async () => {
+    const { records, settings: config } = await trail(3);
+    assert.deepEqual(
+      records.map((r) => r.sequence),
+      [1, 2, 3],
+    );
+    assert.equal(verifyChain(records, config).valid, true);
+  });
+
+  it('detects an edited record', async () => {
+    const { records, settings: config } = await trail(3);
+    records[1]!.action = 'invoice.deleted';
+    const result = verifyChain(records, config);
+    assert.equal(result.valid, false);
+    assert.ok(result.breaks.some((b) => b.reason === 'hash-mismatch' && b.sequence === 2));
+  });
+
+  it('detects a removed record', async () => {
+    const { records, settings: config } = await trail(3);
+    const result = verifyChain([records[0]!, records[2]!], config);
+    assert.equal(result.valid, false);
+    assert.ok(result.breaks.some((b) => b.reason === 'sequence-gap'));
+    assert.ok(result.breaks.some((b) => b.reason === 'broken-link'));
+  });
+
+  it('continues the chain after a restart', async () => {
+    const config = settings();
+    const sink = new MemoryAuditSink(config);
+    await new AuditRecorder(config, sink).record({ action: 'a', outcome: 'success', actorId: 'system' });
+    await new AuditRecorder(config, sink).record({ action: 'b', outcome: 'success', actorId: 'system' });
+    assert.equal(verifyChain(await sink.readAll(), config).valid, true);
+  });
+});
+
+describe('audit redaction', () => {
+  it('replaces configured fields at any depth before writing', async () => {
+    const config = settings();
+    const sink = new MemoryAuditSink(config);
+    await new AuditRecorder(config, sink).record({
+      action: 'user.login',
+      outcome: 'failure',
+      actorId: 'user-1',
+      metadata: { attempt: 2, credentials: { password: 'hunter2', Token: 'abc' } },
+    });
+    const [record] = await sink.readAll();
+    assert.ok(record);
+    const credentials = record.metadata.credentials as Record<string, unknown>;
+    assert.equal(credentials.password, config.redactPlaceholder);
+    assert.equal(credentials.Token, config.redactPlaceholder);
+    assert.equal(record.metadata.attempt, 2);
+  });
+});
+
+describe('audit event validation', () => {
+  it('rejects an event without an actor', async () => {
+    const config = settings();
+    const recorder = new AuditRecorder(config, new MemoryAuditSink(config));
+    await assert.rejects(
+      () => recorder.record({ action: 'x', outcome: 'success', actorId: '' }),
+      AuditEventError,
+    );
+  });
+});
+
+describe('canonical serialization', () => {
+  it('is independent of key insertion order', () => {
+    assert.equal(canonicalize({ b: 1, a: { d: 2, c: 3 } }), canonicalize({ a: { c: 3, d: 2 }, b: 1 }));
+  });
+});

package/templates/layers/audit-log/files/tests/test_audit_log.py

@@ -0,0 +1,91 @@
+from dataclasses import replace
+
+import pytest
+
+from {{ solutionName | snake }}.audit.chain import verify_chain
+from {{ solutionName | snake }}.audit.event import AuditEvent, AuditEventError
+from {{ solutionName | snake }}.audit.recorder import AuditRecorder
+from {{ solutionName | snake }}.audit.redact import canonical
+from {{ solutionName | snake }}.audit.settings import AuditSettings
+from {{ solutionName | snake }}.audit.sinks import MemoryAuditSink
+
+
+def settings() -> AuditSettings:
+    return AuditSettings(sink="memory")
+
+
+def trail(count: int) -> tuple[list, AuditSettings, MemoryAuditSink]:
+    config = settings()
+    sink = MemoryAuditSink(config)
+    recorder = AuditRecorder(config, sink)
+    for index in range(1, count + 1):
+        recorder.record(
+            AuditEvent(
+                action="invoice.approved",
+                outcome="success",
+                actor_id=f"user-{index}",
+                resource_type="invoice",
+                resource_id=str(index),
+            )
+        )
+    return sink.read_all(), config, sink
+
+
+def test_sequence_is_contiguous_and_chain_verifies() -> None:
+    records, config, _ = trail(3)
+    assert [record.sequence for record in records] == [1, 2, 3]
+    assert verify_chain(records, config).valid
+
+
+def test_edited_record_is_detected() -> None:
+    records, config, _ = trail(3)
+    tampered = list(records)
+    tampered[1] = replace(tampered[1], action="invoice.deleted")
+    result = verify_chain(tampered, config)
+    assert not result.valid
+    assert any(b.reason == "hash-mismatch" and b.sequence == 2 for b in result.breaks)
+
+
+def test_removed_record_is_detected() -> None:
+    records, config, _ = trail(3)
+    result = verify_chain([records[0], records[2]], config)
+    assert not result.valid
+    assert any(b.reason == "sequence-gap" for b in result.breaks)
+    assert any(b.reason == "broken-link" for b in result.breaks)
+
+
+def test_chain_continues_after_restart() -> None:
+    config = settings()
+    sink = MemoryAuditSink(config)
+    AuditRecorder(config, sink).record(AuditEvent(action="a", outcome="success", actor_id="system"))
+    AuditRecorder(config, sink).record(AuditEvent(action="b", outcome="success", actor_id="system"))
+    assert verify_chain(sink.read_all(), config).valid
+
+
+def test_configured_fields_are_redacted_at_any_depth() -> None:
+    config = settings()
+    sink = MemoryAuditSink(config)
+    AuditRecorder(config, sink).record(
+        AuditEvent(
+            action="user.login",
+            outcome="failure",
+            actor_id="user-1",
+            metadata={"attempt": 2, "credentials": {"password": "hunter2", "Token": "abc"}},
+        )
+    )
+    record = sink.read_all()[0]
+    credentials = record.metadata["credentials"]
+    assert credentials["password"] == config.redact_placeholder
+    assert credentials["Token"] == config.redact_placeholder
+    assert record.metadata["attempt"] == 2
+
+
+def test_event_without_actor_is_rejected() -> None:
+    config = settings()
+    recorder = AuditRecorder(config, MemoryAuditSink(config))
+    with pytest.raises(AuditEventError):
+        recorder.record(AuditEvent(action="x", outcome="success", actor_id=""))
+
+
+def test_canonical_form_is_independent_of_key_order() -> None:
+    assert canonical({"b": 1, "a": {"d": 2, "c": 3}}) == canonical({"a": {"c": 3, "d": 2}, "b": 1})

package/templates/layers/auth-jwt/blueprint.yaml

@@ -0,0 +1,124 @@
+id: auth-jwt
+kind: layer
+name: Self-issued JWT auth
+description: >-
+  First-party authentication: the service signs its own short-lived HS256 access
+  tokens, hashes passwords with Argon2id, and rotates opaque refresh tokens with
+  reuse detection. No external identity provider.
+tags: [auth, security, jwt, password]
+
+# No `requires`: the layer ships storage *interfaces* plus an in-memory implementation,
+# so it composes with any db layer (or none) instead of forcing one.
+requires: []
+
+# auth-oidc delegates identity to an external IdP and verifies tokens it did not sign.
+# Both layers own the same wiring, config keys, and principal — running them together
+# yields two competing authentication schemes on one pipeline.
+conflicts: [auth-oidc]
+
+# Capability names other layers/architectures can reason about.
+provides: [auth, jwt-issuer, password-hashing]
+
+variables:
+  - name: authAccessTtlSeconds
+    prompt: Access token lifetime (seconds)
+    type: number
+    default: 900
+    required: false
+
+  - name: authRefreshTtlSeconds
+    prompt: Refresh token lifetime (seconds)
+    type: number
+    default: 2592000
+    required: false
+
+  - name: authTestRunner
+    prompt: Test runner for the auth suite
+    type: select
+    choices:
+      - { value: node, label: 'node:test (no dependency)' }
+      - { value: vitest, label: 'Vitest' }
+    default: node
+    required: false
+    when: "stack == 'typescript' || stack == 'node'"
+
+files:
+  # ── TypeScript / Node ───────────────────────────────────────────────────────
+  # Single `*` never descends into tests/, so the suite below is not double-claimed.
+  # The directory cannot be `__tests__`: renderPath would read it as a path token.
+  - from: files/src/auth/*.ts
+    when: "stack == 'typescript' || stack == 'node'"
+  # `.test.ts` is discovered by `node --test`; `.spec.ts` by Vitest. Emitting only one
+  # keeps the base's existing test command green either way.
+  - from: files/src/auth/tests/auth.test.ts
+    when: "(stack == 'typescript' || stack == 'node') && authTestRunner == 'node'"
+  - from: files/src/auth/tests/auth.spec.ts
+    when: "(stack == 'typescript' || stack == 'node') && authTestRunner == 'vitest'"
+
+  # ── Python ──────────────────────────────────────────────────────────────────
+  # Lands inside the base's own package, so it imports as <solution>.auth.
+  - from: files/src/__solutionName.snake__/auth/*.py
+    when: "stack == 'python'"
+  - from: files/tests/auth/*.py
+    when: "stack == 'python'"
+
+  # ── Go ──────────────────────────────────────────────────────────────────────
+  - from: files/internal/auth/*.go
+    when: "stack == 'go'"
+
+  # ── .NET ────────────────────────────────────────────────────────────────────
+  # A class library of its own: it builds standalone and needs no edit to the API project.
+  - from: files/src/__solutionName.dot__.Auth/*
+    when: "stack == 'dotnet'"
+
+  # ── Shared ──────────────────────────────────────────────────────────────────
+  # .NET binds the `Auth:` configuration section instead; it ships its own sample.
+  - from: files/.env.auth.example
+    when: "stack != 'dotnet'"
+  - from: files/docs/auth-jwt.md
+
+  # Code that imports a package the manifest never installs does not build (ADR 0005).
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # Declared, not fetched by a post-apply step: `go get` after generation leaves the
+  # first build missing the module (ADR 0005, spec 003).
+  - from: files/go.mod
+    to: .
+    onConflict: merge
+    when: "stack == 'go'"
+
+  # Declared, not installed by a post-apply step: a package added after generation is
+  # missing from the first install (ADR 0005, spec 003).
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # Manifest-only edits. Nothing here installs, so a pnpm/uv repo never gains a
+  # stray npm lockfile; `docs/auth-jwt.md` states the install step.
+  - run: npm pkg set dependencies.jose=^6.2.3 "dependencies.@node-rs/argon2"=^2.0.2
+    when: "stack == 'typescript' || stack == 'node'"
+    optional: true
+  - run: uv add "pyjwt[crypto]==2.13.0" "pwdlib[argon2]==0.3.0"
+    when: "stack == 'python'"
+    optional: true
+  # The csproj already pins its PackageReference; this only joins the solution.

package/templates/layers/auth-jwt/files/.env.auth.example

@@ -0,0 +1,17 @@
+# Auth (auth-jwt layer) — append these to your .env.
+# Defaults live in the auth config module; anything unset here uses them.
+
+# Required. No default: an absent secret must fail the boot, not silently weaken it.
+# Generate with: openssl rand -base64 48
+AUTH_JWT_SECRET=
+
+# AUTH_JWT_ISSUER={{ solutionName | kebab }}
+# AUTH_JWT_AUDIENCE={{ solutionName | kebab }}
+
+# AUTH_ACCESS_TTL_SECONDS={{ authAccessTtlSeconds }}
+# AUTH_REFRESH_TTL_SECONDS={{ authRefreshTtlSeconds }}
+
+# Argon2id cost. Defaults are the OWASP minimum; raise memory before iterations.
+# AUTH_ARGON2_MEMORY_KIB=19456
+# AUTH_ARGON2_ITERATIONS=2
+# AUTH_ARGON2_PARALLELISM=1

package/templates/layers/auth-jwt/files/Directory.Packages.props

@@ -0,0 +1,5 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.10" />
+  </ItemGroup>
+</Project>

package/templates/layers/auth-jwt/files/__solutionName.dot__.slnx

@@ -0,0 +1,5 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | dot }}.Auth/{{ solutionName | dot }}.Auth.csproj" />
+  </Folder>
+</Solution>