@jagit/shared 0.0.1

package/dist/approval-bridge.d.ts

@@ -0,0 +1,12 @@
+export interface WaitForApprovalDecisionOpts {
+    redisUrl: string;
+    jobId: string;
+    approvalId: string;
+    timeoutMs: number;
+    denyOptionId: string;
+}
+/**
+ * Subscribes to the job control channel and waits for an approval signal
+ * matching `approvalId`. On timeout returns `denyOptionId`.
+ */
+export declare function waitForApprovalDecision(opts: WaitForApprovalDecisionOpts): Promise<string>;

package/dist/approval-bridge.js

@@ -0,0 +1,35 @@
+import { makeRedis, controlChannel } from "./events.js";
+/**
+ * Subscribes to the job control channel and waits for an approval signal
+ * matching `approvalId`. On timeout returns `denyOptionId`.
+ */
+export function waitForApprovalDecision(opts) {
+    const redis = makeRedis(opts.redisUrl);
+    const channel = controlChannel(opts.jobId);
+    return new Promise((resolve) => {
+        let resolved = false;
+        const finish = (optionId) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            redis.quit().catch(() => { });
+            resolve(optionId);
+        };
+        const timer = setTimeout(() => finish(opts.denyOptionId), opts.timeoutMs);
+        redis.subscribe(channel).catch(() => finish(opts.denyOptionId));
+        redis.on("message", (_ch, msg) => {
+            try {
+                const signal = JSON.parse(msg);
+                if (signal.type === "approval" &&
+                    signal.approvalId === opts.approvalId &&
+                    signal.chosenOptionId) {
+                    finish(signal.chosenOptionId);
+                }
+            }
+            catch {
+                /* ignore malformed */
+            }
+        });
+    });
+}

package/dist/branch.d.ts

@@ -0,0 +1,10 @@
+export interface IssueRef {
+    key: string;
+    type: string;
+    summary: string;
+}
+export type BranchRules = Record<string, string> & {
+    default?: string;
+};
+export declare function deriveBranchName(issue: IssueRef, rules: BranchRules): string;
+export declare function extractIssueKey(branch: string): string | null;

package/dist/branch.js

@@ -0,0 +1,20 @@
+function slugify(s) {
+    return s
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "") // strip combining diacritics (Unicode property escape)
+        .replace(/[^\w\s-]/g, "") // strip non-word chars
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_]+/g, "-")
+        .replace(/-+/g, "-")
+        .slice(0, 40)
+        .replace(/-$/, "");
+}
+export function deriveBranchName(issue, rules) {
+    const prefix = rules[issue.type] ?? rules.default ?? "feature/";
+    return `${prefix}${issue.key}-${slugify(issue.summary)}`;
+}
+export function extractIssueKey(branch) {
+    const match = branch.match(/([A-Z][A-Z0-9]+-\d+)/);
+    return match ? match[1] : null;
+}

package/dist/branch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/branch.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { deriveBranchName, extractIssueKey } from "./branch.js";
+const RULES = { Bug: "bugfix/", Story: "feature/", Task: "feature/", default: "feature/" };
+describe("deriveBranchName", () => {
+    it("uses type-specific prefix for Bug", () => {
+        expect(deriveBranchName({ key: "JAGIT-12", type: "Bug", summary: "Fix Login!" }, RULES)).toBe("bugfix/JAGIT-12-fix-login");
+    });
+    it("falls back to default prefix for unknown type", () => {
+        expect(deriveBranchName({ key: "JAGIT-9", type: "Spike", summary: "Explore caching" }, RULES)).toBe("feature/JAGIT-9-explore-caching");
+    });
+    it("truncates long summaries to 40 chars in the slug", () => {
+        const summary = "This is a very long summary that should be truncated at forty chars";
+        const branch = deriveBranchName({ key: "X-1", type: "Bug", summary }, RULES);
+        // slug portion (after "bugfix/X-1-") must be ≤ 40 chars
+        const slug = branch.replace("bugfix/X-1-", "");
+        expect(slug.length).toBeLessThanOrEqual(40);
+    });
+    it("strips non-ASCII and special characters", () => {
+        expect(deriveBranchName({ key: "X-2", type: "Bug", summary: "Ünîcödé & special!!" }, RULES)).toBe("bugfix/X-2-unicode-special");
+    });
+});
+describe("extractIssueKey", () => {
+    it("extracts a key from a feature branch", () => {
+        expect(extractIssueKey("feature/JAGIT-12-fix-login")).toBe("JAGIT-12");
+    });
+    it("extracts a key from a bugfix branch", () => {
+        expect(extractIssueKey("bugfix/PROJ-99-some-bug")).toBe("PROJ-99");
+    });
+    it("returns null when no key is present", () => {
+        expect(extractIssueKey("main")).toBeNull();
+    });
+});

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export type RawEnv = NodeJS.ProcessEnv | Record<string, string | undefined>;
+export declare function parseConfig(env: RawEnv): {
+    databaseUrl: string;
+    redisUrl: string;
+    encryptionKey: string;
+    maxConcurrentAgents: number;
+    maxRetries: number;
+    approvalTimeoutMs: number;
+    acpRequestTimeoutMs: number;
+    anthropicApiKey: string;
+    telegramBotToken: string;
+    publicBaseUrl: string;
+    apiPort: number;
+    webhookSecret: string;
+    dashboardApiToken: string;
+};
+export type AppConfig = ReturnType<typeof parseConfig>;
+/** Loads config from `process.env`. Throws if any required var is missing. */
+export declare const loadConfig: () => AppConfig;

package/dist/config.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+const Schema = z.object({
+    DATABASE_URL: z.string().min(1),
+    REDIS_URL: z.string().min(1),
+    APP_ENCRYPTION_KEY: z.string().min(1),
+    MAX_CONCURRENT_AGENTS: z.coerce.number().int().positive(),
+    MAX_RETRIES: z.coerce.number().int().nonnegative(),
+    APPROVAL_TIMEOUT_MS: z.coerce.number().int().positive(),
+    ACP_REQUEST_TIMEOUT_MS: z.coerce.number().int().positive().default(600_000),
+    ANTHROPIC_API_KEY: z.string().min(1),
+    TELEGRAM_BOT_TOKEN: z.string().min(1),
+    PUBLIC_BASE_URL: z.string().url(),
+    API_PORT: z.coerce.number().int().positive().default(3000),
+    API_WEBHOOK_SECRET: z.string().min(1),
+    DASHBOARD_API_TOKEN: z.string().min(1),
+});
+export function parseConfig(env) {
+    const p = Schema.parse(env);
+    return {
+        databaseUrl: p.DATABASE_URL,
+        redisUrl: p.REDIS_URL,
+        encryptionKey: p.APP_ENCRYPTION_KEY,
+        maxConcurrentAgents: p.MAX_CONCURRENT_AGENTS,
+        maxRetries: p.MAX_RETRIES,
+        approvalTimeoutMs: p.APPROVAL_TIMEOUT_MS,
+        acpRequestTimeoutMs: p.ACP_REQUEST_TIMEOUT_MS,
+        anthropicApiKey: p.ANTHROPIC_API_KEY,
+        telegramBotToken: p.TELEGRAM_BOT_TOKEN,
+        publicBaseUrl: p.PUBLIC_BASE_URL,
+        apiPort: p.API_PORT,
+        webhookSecret: p.API_WEBHOOK_SECRET,
+        dashboardApiToken: p.DASHBOARD_API_TOKEN,
+    };
+}
+/** Loads config from `process.env`. Throws if any required var is missing. */
+export const loadConfig = () => parseConfig(process.env);

package/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { parseConfig } from "./config.js";
+const FULL_ENV = {
+    DATABASE_URL: "postgresql://jagit:jagit@localhost:5432/jagit",
+    REDIS_URL: "redis://localhost:6379",
+    APP_ENCRYPTION_KEY: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa==",
+    MAX_CONCURRENT_AGENTS: "3",
+    MAX_RETRIES: "3",
+    APPROVAL_TIMEOUT_MS: "1800000",
+    ANTHROPIC_API_KEY: "sk-ant-test",
+    TELEGRAM_BOT_TOKEN: "1234567890:AAAA",
+    PUBLIC_BASE_URL: "http://localhost:3000",
+    API_PORT: "3000",
+    API_WEBHOOK_SECRET: "webhook-secret",
+    DASHBOARD_API_TOKEN: "dash-token",
+};
+describe("parseConfig", () => {
+    it("rejects an empty env (missing keys)", () => {
+        expect(() => parseConfig({})).toThrow();
+    });
+    it("parses a complete env and coerces numbers", () => {
+        const cfg = parseConfig(FULL_ENV);
+        expect(cfg.maxConcurrentAgents).toBe(3);
+        expect(cfg.approvalTimeoutMs).toBe(1800000);
+        expect(cfg.apiPort).toBe(3000);
+        expect(cfg.dashboardApiToken).toBe("dash-token");
+    });
+    it("rejects a non-URL PUBLIC_BASE_URL", () => {
+        expect(() => parseConfig({ ...FULL_ENV, PUBLIC_BASE_URL: "not-a-url" })).toThrow();
+    });
+});

package/dist/credentials.d.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+export declare const CredentialKindSchema: z.ZodEnum<{
+    jira: "jira";
+    gitlab: "gitlab";
+    telegram: "telegram";
+    anthropic: "anthropic";
+}>;
+export type CredentialKind = z.infer<typeof CredentialKindSchema>;
+export declare const JiraCredentialSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        baseUrl: z.ZodString;
+        botAccountId: z.ZodString;
+    }, z.core.$catchall<z.ZodString>>;
+    secrets: z.ZodObject<{
+        email: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const GitLabCredentialSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        baseUrl: z.ZodString;
+    }, z.core.$catchall<z.ZodString>>;
+    secrets: z.ZodObject<{
+        token: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const AnthropicCredentialSchema: z.ZodObject<{
+    meta: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        baseUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodString>>>>;
+    secrets: z.ZodObject<{
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const TelegramCredentialSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        chatId: z.ZodString;
+    }, z.core.$catchall<z.ZodString>>;
+    secrets: z.ZodObject<{
+        botToken: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Returns the required secret keys for a given credential kind.
+ */
+export declare function credentialSecretKeys(kind: CredentialKind): string[];
+/**
+ * Validates a full credential input against the appropriate kind schema.
+ */
+export declare function validateCredential(kind: CredentialKind, input: unknown): {
+    meta: {
+        [x: string]: string;
+        baseUrl: string;
+    };
+    secrets: {
+        token: string;
+    };
+} | {
+    meta: {
+        [x: string]: string;
+        baseUrl?: string | undefined;
+    };
+    secrets: {
+        apiKey: string;
+    };
+} | {
+    meta: {
+        [x: string]: string;
+        chatId: string;
+    };
+    secrets: {
+        botToken: string;
+    };
+};
+/**
+ * Merges provided secrets into existing encrypted secrets.
+ * - If existingEncrypted is null, encrypts only the provided secrets.
+ * - Non-empty provided fields overwrite existing ones.
+ * - Omitted or blank/empty string fields keep existing values.
+ * - Returns a new encrypted blob (never plaintext).
+ */
+export declare function mergeSecrets(existingEncrypted: string | null, provided: Record<string, string | undefined>, keyB64: string): string;

package/dist/credentials.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { encrypt, decrypt } from "./crypto.js";
+export const CredentialKindSchema = z.enum(["jira", "gitlab", "telegram", "anthropic"]);
+export const JiraCredentialSchema = z.object({
+    meta: z
+        .object({
+        baseUrl: z.string().url(),
+        botAccountId: z.string().min(1),
+    })
+        .catchall(z.string()),
+    secrets: z.object({
+        email: z.string().min(1),
+        token: z.string().min(1),
+    }),
+});
+export const GitLabCredentialSchema = z.object({
+    meta: z
+        .object({
+        baseUrl: z.string().url(),
+    })
+        .catchall(z.string()),
+    secrets: z.object({
+        token: z.string().min(1),
+    }),
+});
+export const AnthropicCredentialSchema = z.object({
+    meta: z
+        .object({
+        baseUrl: z.string().url().optional(),
+    })
+        .catchall(z.string())
+        .optional()
+        .default({}),
+    secrets: z.object({
+        apiKey: z.string().min(1),
+    }),
+});
+export const TelegramCredentialSchema = z.object({
+    meta: z
+        .object({
+        chatId: z.string().min(1),
+    })
+        .catchall(z.string()),
+    secrets: z.object({
+        botToken: z.string().min(1),
+    }),
+});
+/**
+ * Returns the required secret keys for a given credential kind.
+ */
+export function credentialSecretKeys(kind) {
+    switch (kind) {
+        case "jira":
+            return ["email", "token"];
+        case "gitlab":
+            return ["token"];
+        case "anthropic":
+            return ["apiKey"];
+        case "telegram":
+            return ["botToken"];
+    }
+}
+const KindToSchema = {
+    jira: JiraCredentialSchema,
+    gitlab: GitLabCredentialSchema,
+    anthropic: AnthropicCredentialSchema,
+    telegram: TelegramCredentialSchema,
+};
+/**
+ * Validates a full credential input against the appropriate kind schema.
+ */
+export function validateCredential(kind, input) {
+    return KindToSchema[kind].parse(input);
+}
+/**
+ * Merges provided secrets into existing encrypted secrets.
+ * - If existingEncrypted is null, encrypts only the provided secrets.
+ * - Non-empty provided fields overwrite existing ones.
+ * - Omitted or blank/empty string fields keep existing values.
+ * - Returns a new encrypted blob (never plaintext).
+ */
+export function mergeSecrets(existingEncrypted, provided, keyB64) {
+    const existing = existingEncrypted ? JSON.parse(decrypt(existingEncrypted, keyB64)) : {};
+    const merged = {};
+    for (const [key, value] of Object.entries(existing)) {
+        merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(provided)) {
+        if (value !== undefined && value.trim() !== "") {
+            merged[key] = value.trim();
+        }
+    }
+    return encrypt(JSON.stringify(merged), keyB64);
+}

package/dist/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credentials.test.js

@@ -0,0 +1,206 @@
+import { describe, expect, it } from "vitest";
+import { CredentialKindSchema, JiraCredentialSchema, GitLabCredentialSchema, AnthropicCredentialSchema, TelegramCredentialSchema, credentialSecretKeys, validateCredential, mergeSecrets, } from "./credentials.js";
+import { decrypt } from "./crypto.js";
+const KEY = Buffer.alloc(32, 11).toString("base64");
+describe("CredentialKindSchema", () => {
+    it("accepts valid kinds", () => {
+        expect(() => CredentialKindSchema.parse("jira")).not.toThrow();
+        expect(() => CredentialKindSchema.parse("gitlab")).not.toThrow();
+        expect(() => CredentialKindSchema.parse("anthropic")).not.toThrow();
+        expect(() => CredentialKindSchema.parse("telegram")).not.toThrow();
+    });
+    it("rejects invalid kinds", () => {
+        expect(() => CredentialKindSchema.parse("unknown")).toThrow();
+    });
+});
+describe("JiraCredentialSchema", () => {
+    it("accepts valid jira credentials", () => {
+        const result = JiraCredentialSchema.parse({
+            meta: { baseUrl: "https://jira.example.com", botAccountId: "123" },
+            secrets: { email: "bot@example.com", token: "tok" },
+        });
+        expect(result.meta.baseUrl).toBe("https://jira.example.com");
+        expect(result.secrets.email).toBe("bot@example.com");
+    });
+    it("rejects missing required meta fields", () => {
+        expect(() => JiraCredentialSchema.parse({
+            meta: { baseUrl: "https://jira.example.com" },
+            secrets: { email: "bot@example.com", token: "tok" },
+        })).toThrow();
+    });
+    it("rejects missing required secret fields", () => {
+        expect(() => JiraCredentialSchema.parse({
+            meta: { baseUrl: "https://jira.example.com", botAccountId: "123" },
+            secrets: { email: "bot@example.com" },
+        })).toThrow();
+    });
+});
+describe("GitLabCredentialSchema", () => {
+    it("accepts valid gitlab credentials", () => {
+        const result = GitLabCredentialSchema.parse({
+            meta: { baseUrl: "https://gitlab.com" },
+            secrets: { token: "glpat-xxx" },
+        });
+        expect(result.meta.baseUrl).toBe("https://gitlab.com");
+        expect(result.secrets.token).toBe("glpat-xxx");
+    });
+    it("rejects missing required secret fields", () => {
+        expect(() => GitLabCredentialSchema.parse({
+            meta: { baseUrl: "https://gitlab.com" },
+            secrets: {},
+        })).toThrow();
+    });
+});
+describe("AnthropicCredentialSchema", () => {
+    it("accepts valid anthropic credentials", () => {
+        const result = AnthropicCredentialSchema.parse({
+            meta: {},
+            secrets: { apiKey: "sk-ant-xxx" },
+        });
+        expect(result.secrets.apiKey).toBe("sk-ant-xxx");
+    });
+    it("rejects missing required secret fields", () => {
+        expect(() => AnthropicCredentialSchema.parse({
+            meta: {},
+            secrets: {},
+        })).toThrow();
+    });
+});
+describe("TelegramCredentialSchema", () => {
+    it("accepts valid telegram credentials", () => {
+        const result = TelegramCredentialSchema.parse({
+            meta: { chatId: "123456" },
+            secrets: { botToken: "123:abc" },
+        });
+        expect(result.meta.chatId).toBe("123456");
+        expect(result.secrets.botToken).toBe("123:abc");
+    });
+    it("rejects missing required meta fields", () => {
+        expect(() => TelegramCredentialSchema.parse({
+            meta: {},
+            secrets: { botToken: "123:abc" },
+        })).toThrow();
+    });
+    it("rejects missing required secret fields", () => {
+        expect(() => TelegramCredentialSchema.parse({
+            meta: { chatId: "123456" },
+            secrets: {},
+        })).toThrow();
+    });
+});
+describe("URL validation", () => {
+    it("rejects malformed baseUrl in jira", () => {
+        expect(() => JiraCredentialSchema.parse({
+            meta: { baseUrl: "not-a-url", botAccountId: "123" },
+            secrets: { email: "bot@example.com", token: "tok" },
+        })).toThrow();
+    });
+    it("rejects malformed baseUrl in gitlab", () => {
+        expect(() => GitLabCredentialSchema.parse({
+            meta: { baseUrl: "not-a-url" },
+            secrets: { token: "glpat-xxx" },
+        })).toThrow();
+    });
+    it("rejects malformed baseUrl in anthropic meta", () => {
+        expect(() => AnthropicCredentialSchema.parse({
+            meta: { baseUrl: "not-a-url" },
+            secrets: { apiKey: "sk-ant-xxx" },
+        })).toThrow();
+    });
+});
+describe("credentialSecretKeys", () => {
+    it("returns correct keys for jira", () => {
+        expect(credentialSecretKeys("jira")).toEqual(["email", "token"]);
+    });
+    it("returns correct keys for gitlab", () => {
+        expect(credentialSecretKeys("gitlab")).toEqual(["token"]);
+    });
+    it("returns correct keys for anthropic", () => {
+        expect(credentialSecretKeys("anthropic")).toEqual(["apiKey"]);
+    });
+    it("returns correct keys for telegram", () => {
+        expect(credentialSecretKeys("telegram")).toEqual(["botToken"]);
+    });
+});
+describe("validateCredential", () => {
+    it("validates jira credentials", () => {
+        const result = validateCredential("jira", {
+            meta: { baseUrl: "https://jira.example.com", botAccountId: "123" },
+            secrets: { email: "bot@example.com", token: "tok" },
+        });
+        expect(result.meta.baseUrl).toBe("https://jira.example.com");
+    });
+    it("validates gitlab credentials", () => {
+        const result = validateCredential("gitlab", {
+            meta: { baseUrl: "https://gitlab.com" },
+            secrets: { token: "glpat-xxx" },
+        });
+        expect(result.meta.baseUrl).toBe("https://gitlab.com");
+    });
+    it("validates anthropic credentials", () => {
+        const result = validateCredential("anthropic", {
+            meta: {},
+            secrets: { apiKey: "sk-ant-xxx" },
+        });
+        expect(result.secrets.apiKey).toBe("sk-ant-xxx");
+    });
+    it("validates telegram credentials", () => {
+        const result = validateCredential("telegram", {
+            meta: { chatId: "123456" },
+            secrets: { botToken: "123:abc" },
+        });
+        expect(result.meta.chatId).toBe("123456");
+    });
+    it("rejects invalid credentials", () => {
+        expect(() => validateCredential("jira", {
+            meta: { baseUrl: "not-a-url", botAccountId: "123" },
+            secrets: { email: "bot@example.com", token: "tok" },
+        })).toThrow();
+    });
+});
+describe("mergeSecrets", () => {
+    it("encrypts provided secrets when no existing blob", () => {
+        const provided = { apiKey: "sk-ant-new" };
+        const result = mergeSecrets(null, provided, KEY);
+        expect(typeof result).toBe("string");
+        expect(result.split(".")).toHaveLength(3);
+        const decrypted = JSON.parse(decrypt(result, KEY));
+        expect(decrypted).toEqual({ apiKey: "sk-ant-new" });
+    });
+    it("overwrites existing secrets with provided non-empty values", () => {
+        const existing = mergeSecrets(null, { apiKey: "old-key", orgId: "org-1" }, KEY);
+        const result = mergeSecrets(existing, { apiKey: "new-key" }, KEY);
+        const decrypted = JSON.parse(decrypt(result, KEY));
+        expect(decrypted).toEqual({ apiKey: "new-key", orgId: "org-1" });
+    });
+    it("keeps existing secrets when provided fields are omitted", () => {
+        const existing = mergeSecrets(null, { token: "old-token" }, KEY);
+        const result = mergeSecrets(existing, {}, KEY);
+        const decrypted = JSON.parse(decrypt(result, KEY));
+        expect(decrypted).toEqual({ token: "old-token" });
+    });
+    it("keeps existing secrets when provided fields are blank", () => {
+        const existing = mergeSecrets(null, { token: "old-token", email: "a@b.com" }, KEY);
+        const result = mergeSecrets(existing, { token: "", email: undefined }, KEY);
+        const decrypted = JSON.parse(decrypt(result, KEY));
+        expect(decrypted).toEqual({ token: "old-token", email: "a@b.com" });
+    });
+    it("trims whitespace-only values before storing", () => {
+        const existing = mergeSecrets(null, { token: "old-token" }, KEY);
+        const result = mergeSecrets(existing, { token: "   new-token   " }, KEY);
+        const decrypted = JSON.parse(decrypt(result, KEY));
+        expect(decrypted).toEqual({ token: "new-token" });
+    });
+    it("returns a new ciphertext (re-encrypts)", () => {
+        const existing = mergeSecrets(null, { token: "old" }, KEY);
+        const result = mergeSecrets(existing, { token: "new" }, KEY);
+        expect(result).not.toBe(existing);
+        const decrypted = JSON.parse(decrypt(result, KEY));
+        expect(decrypted).toEqual({ token: "new" });
+    });
+    it("never returns plaintext", () => {
+        const result = mergeSecrets(null, { key: "val" }, KEY);
+        expect(result).not.toContain("val");
+        expect(result).not.toContain("key");
+    });
+});

package/dist/crypto.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Encrypts `plain` with AES-256-GCM.
+ * Output format: "<iv_b64url>.<tag_b64url>.<ciphertext_b64url>"
+ * Uses base64url (no padding) so that appending characters to a segment
+ * always changes the decoded bytes — enabling reliable tamper detection.
+ */
+export declare function encrypt(plain: string, keyB64: string): string;
+/**
+ * Decrypts a payload produced by `encrypt`.
+ * Throws if the key is wrong or the ciphertext was tampered with.
+ */
+export declare function decrypt(payload: string, keyB64: string): string;

package/dist/crypto.js

@@ -0,0 +1,29 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+/**
+ * Encrypts `plain` with AES-256-GCM.
+ * Output format: "<iv_b64url>.<tag_b64url>.<ciphertext_b64url>"
+ * Uses base64url (no padding) so that appending characters to a segment
+ * always changes the decoded bytes — enabling reliable tamper detection.
+ */
+export function encrypt(plain, keyB64) {
+    const key = Buffer.from(keyB64, "base64");
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const enc = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [iv, tag, enc].map((b) => b.toString("base64url")).join(".");
+}
+/**
+ * Decrypts a payload produced by `encrypt`.
+ * Throws if the key is wrong or the ciphertext was tampered with.
+ */
+export function decrypt(payload, keyB64) {
+    const key = Buffer.from(keyB64, "base64");
+    const parts = payload.split(".");
+    if (parts.length !== 3)
+        throw new Error("Invalid ciphertext format");
+    const [iv, tag, enc] = parts.map((s) => Buffer.from(s, "base64url"));
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(enc), decipher.final()]).toString("utf8");
+}

package/dist/crypto.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/crypto.test.js

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { encrypt, decrypt } from "./crypto.js";
+const KEY = Buffer.alloc(32, 7).toString("base64");
+describe("crypto", () => {
+    it("round-trips plaintext", () => {
+        const ciphertext = encrypt("super-secret", KEY);
+        expect(ciphertext).not.toBe("super-secret");
+        expect(decrypt(ciphertext, KEY)).toBe("super-secret");
+    });
+    it("uses a unique IV each call (ciphertexts differ)", () => {
+        const a = encrypt("x", KEY);
+        const b = encrypt("x", KEY);
+        expect(a).not.toBe(b);
+    });
+    it("throws on tampered ciphertext", () => {
+        const c = encrypt("data", KEY);
+        const [iv, tag, enc] = c.split(".");
+        expect(() => decrypt([iv, tag, enc + "XX"].join("."), KEY)).toThrow();
+    });
+});