Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
4188932
feat(kin): audit events for cancelled and expired actions (APPR-10)
Surajsm60720 Nov 8, 2026
c761ebc
feat(kin): hash-chained approval audit log (APPR-10)
Surajsm60720 Nov 8, 2026
0bf3920
Merge remote-tracking branch 'origin/kin-appr-2-pending-actions' into…
Surajsm60720 Nov 8, 2026
51b67a3
fix(kin): owner-only audit, corrupt-row markers, org-scoped grant_rej…
Surajsm60720 Nov 8, 2026
cf84c9c
docs(kin): audit spec covers append-only triggers and the grant_rejec…
Surajsm60720 Nov 8, 2026
bb0e4be
test(kin): mock KinIdentity.owner and split member audit assertions (…
Surajsm60720 Nov 8, 2026
2b819b9
Merge APPR-2 (K009) into APPR-10
Surajsm60720 Nov 8, 2026
5facc8e
fix(kin): drop a duplicate import from the APPR-2 merge (APPR-10)
Surajsm60720 Nov 8, 2026
cd15ad3
Merge remote-tracking branch 'origin/kin-appr-2-pending-actions' into…
Surajsm60720 Nov 8, 2026
5c4e7ac
Merge remote-tracking branch 'origin/kin-appr-2-pending-actions' into…
Surajsm60720 Nov 8, 2026
d3f77da
Merge origin/kin-appr-2-pending-actions into kin-appr-10-audit
Surajsm60720 Nov 8, 2026
b47605d
fix(kin): provide SqlClient to the makeKinHandlers auth test now audi…
Surajsm60720 Nov 8, 2026
e0f8489
Merge remote-tracking branch 'origin/kin-appr-2-pending-actions' into…
Surajsm60720 Nov 8, 2026
b76f19b
Merge branch 'kin-appr-2-pending-actions' into kin-appr-10-audit
Surajsm60720 Nov 8, 2026
c88e769
chore: merge kin-appr-2-pending-actions into kin-appr-10-audit
Surajsm60720 Nov 8, 2026
60a358b
fix(kin): keep audit handlers off the judge's import graph
Surajsm60720 Nov 8, 2026
d537cdf
chore: merge kin-appr-2-pending-actions into kin-appr-10-audit
Surajsm60720 Nov 8, 2026
dc11461
chore: merge kin-appr-2-pending-actions into kin-appr-10-audit
Surajsm60720 Nov 8, 2026
a797daa
Merge branch 'kin-appr-2-pending-actions' into kin-appr-10-audit
Surajsm60720 Nov 8, 2026
2f010d1
fix(server): report kin audit as disabled when Kin is off
Surajsm60720 Nov 8, 2026
7a357f5
Merge branch 'kin-appr-2-pending-actions' into kin-appr-10-audit
Surajsm60720 Nov 8, 2026
4cb4ebe
fix(kin): a lost grant_rejected trace no longer turns a refusal into …
GLDRoger Nov 8, 2026
9bc4313
Merge remote-tracking branch 'origin/kin' into kin-appr-10-audit
GLDRoger Nov 8, 2026
2826fd8
Merge remote-tracking branch 'origin/kin' into kin-appr-10-audit
GLDRoger Nov 8, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
586 changes: 586 additions & 0 deletions apps/server/src/kin/approvals/Audit.test.ts

Large diffs are not rendered by default.

198 changes: 198 additions & 0 deletions apps/server/src/kin/approvals/Audit.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
// @effect-diagnostics nodeBuiltinImport:off -- a synchronous SHA-256 for the hash chain.
import * as NodeCrypto from "node:crypto";

import {
KinAuditEntry,
type KinAuditListInput,
type KinAuditListResult,
type KinAuditVerifyResult,
type KinOrgId,
} from "@t3tools/contracts";
import { stableStringify } from "@t3tools/shared/relaySigning";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import * as SecureRandom from "effect/crypto/SecureRandom";
import * as SqlClient from "effect/sql/SqlClient";

import {
PersistenceDecodeError,
type PersistenceSqlError,
toPersistenceSqlError,
} from "../../persistence/Errors.ts";

/** `prevHash` of each org's first entry. */
const KIN_AUDIT_GENESIS_HASH = "0".repeat(64);
const VERIFY_PAGE = 500;

export type KinAuditAppendInput = Omit<KinAuditEntry, "id" | "seq" | "at" | "prevHash" | "hash">;
type Errors = PersistenceSqlError | PersistenceDecodeError;

const { hash: _hash, ...unhashedFields } = KinAuditEntry.fields;
const encodeUnhashed = Schema.encodeEffect(Schema.Struct(unhashedFields));
const decodeEntry = Schema.decodeUnknownEffect(KinAuditEntry);
const decodeEntryOption = Schema.decodeUnknownOption(KinAuditEntry);

/** Spec section 11: sha256(prevHash ‖ stableStringify(entry without hash)). */
export const kinAuditHash = (unhashed: { readonly prevHash: string }): string =>
NodeCrypto.createHash("sha256")
.update(unhashed.prevHash + stableStringify(unhashed))
.digest("hex");

type AuditRow = {
readonly id: string;
readonly org_id: string;
readonly seq: number;
readonly at: number;
readonly event: string;
readonly entry_json: string;
readonly prev_hash: string;
readonly hash: string;
};

const parseJson = (text: string): unknown => {
try {
return JSON.parse(text);
} catch {
return undefined;
}
};

// One row against its predecessor: canonical bytes, columns, position and both hashes.
const rowIsIntact = (row: AuditRow, expectedSeq: number, prevHash: string): boolean => {
const parsed = parseJson(row.entry_json);
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
if (stableStringify(parsed) !== row.entry_json) return false;
const decoded = decodeEntryOption(parsed);
if (Option.isNone(decoded)) return false;
const entry = decoded.value;
const { hash, ...unhashed } = parsed as typeof KinAuditEntry.Encoded;
return (
row.seq === expectedSeq &&
entry.seq === row.seq &&
entry.id === row.id &&
entry.orgId === row.org_id &&
entry.event === row.event &&
entry.at.epochMilliseconds === row.at &&
entry.prevHash === prevHash &&
row.prev_hash === prevHash &&
hash === row.hash &&
kinAuditHash(unhashed) === row.hash
);
};

export class KinAudit extends Context.Service<
KinAudit,
{
/**
* Appends one entry to the org's chain. Joins the caller's transaction when there is one,
* so a transition and its entry commit or roll back together. Server code only: no RPC or
* MCP tool reaches it.
*/
readonly append: (input: KinAuditAppendInput) => Effect.Effect<KinAuditEntry, Errors>;
readonly list: (input: KinAuditListInput) => Effect.Effect<KinAuditListResult, Errors>;
/** Recomputes the chain from seq 1 and reports the first entry that doesn't hold. */
readonly verify: (input: {
readonly orgId: KinOrgId;
}) => Effect.Effect<KinAuditVerifyResult, Errors>;
}
>()("t3/kin/approvals/Audit/KinAudit") {}

export const make = Effect.gen(function* () {
const sql = yield* SqlClient.SqlClient;

const append = Effect.fn("KinAudit.append")(
function* (input: KinAuditAppendInput) {
// The writer runs BEGIN IMMEDIATE behind one permit, so reading the head and inserting
// the next seq can't interleave with another append; UNIQUE(org_id, seq) backs that up.
return yield* sql.withTransaction(
Effect.gen(function* () {
const now = yield* Clock.currentTimeMillis;
const [head] = yield* sql<{ seq: number; hash: string }>`
SELECT seq, hash FROM kin_audit WHERE org_id = ${input.orgId}
ORDER BY seq DESC LIMIT 1`;
const prevHash = head?.hash ?? KIN_AUDIT_GENESIS_HASH;
const unhashed = yield* encodeUnhashed({
...input,
id: `aud_${SecureRandom.ulidUnsafe()}`,
seq: (head?.seq ?? 0) + 1,
at: DateTime.makeUnsafe(now),
prevHash,
});
const hash = kinAuditHash(unhashed);
const encoded = { ...unhashed, hash };
yield* sql`INSERT INTO kin_audit ${sql.insert({
id: encoded.id,
org_id: encoded.orgId,
seq: encoded.seq,
at: now,
event: encoded.event,
entry_json: stableStringify(encoded),
prev_hash: prevHash,
hash,
})}`;
return yield* decodeEntry(encoded);
}),
);
},
Effect.mapError(toError("KinAudit.append")),
);

const list = Effect.fn("KinAudit.list")(
function* (input: KinAuditListInput) {
const rows = yield* sql<{ seq: number; entry_json: string }>`
SELECT seq, entry_json FROM kin_audit
WHERE org_id = ${input.orgId} AND seq > ${input.afterSeq ?? 0}
ORDER BY seq LIMIT ${input.limit + 1}`;
// One bad row becomes a marker instead of failing every page that includes it.
const entries = rows.slice(0, input.limit).map((row) =>
Option.getOrElse(decodeEntryOption(parseJson(row.entry_json)), () => ({
seq: row.seq,
corrupt: true as const,
})),
);
return { entries, hasMore: rows.length > input.limit };
},
Effect.mapError(toError("KinAudit.list")),
);

const verify = Effect.fn("KinAudit.verify")(
function* (input: { readonly orgId: KinOrgId }) {
let checked = 0;
let prevHash = KIN_AUDIT_GENESIS_HASH;
while (true) {
// Every verified row has seq === checked, so this resumes right after the last one.
const rows = yield* sql<AuditRow>`SELECT * FROM kin_audit
WHERE org_id = ${input.orgId} AND seq > ${checked}
ORDER BY seq LIMIT ${VERIFY_PAGE}`;
if (rows.length === 0) return { ok: true, checked, firstBadSeq: null };
for (const row of rows) {
if (!rowIsIntact(row, checked + 1, prevHash)) {
return { ok: false, checked, firstBadSeq: checked + 1 };
}
checked += 1;
prevHash = row.hash;
}
}
},
Effect.mapError(toError("KinAudit.verify")),
);

return KinAudit.of({ append, list, verify });
});

const isDecodeError = Schema.is(PersistenceDecodeError);
function toError(operation: string) {
return (cause: unknown): Errors =>
isDecodeError(cause)
? cause
: Schema.isSchemaError(cause)
? PersistenceDecodeError.fromSchemaError(operation, cause)
: toPersistenceSqlError(operation)(cause);
}

export const layer = Layer.effect(KinAudit, make);
6 changes: 5 additions & 1 deletion apps/server/src/kin/approvals/PendingActions.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,13 @@ import {
layer as pendingActionsLayer,
type KinPendingActionCreateInput,
} from "./PendingActions.ts";
import * as Audit from "./Audit.ts";

const database = Layer.provideMerge(KinPersistence.layer, Sqlite.layerMemory);
const layer = pendingActionsLayer.pipe(Layer.provideMerge(database));
const layer = pendingActionsLayer.pipe(
Layer.provideMerge(Audit.layer),
Layer.provideMerge(database),
);

const decodeEventId = Schema.decodeSync(KinEventId);
const owner = Schema.decodeSync(KinPersonId)("h_owner");
Expand Down
Loading