opencody-notify 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Software Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# opencody-notify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenCode **V2** server plugin that sends end-to-end encrypted push notifications to the OpenCody iOS app when
+
+- a session run finishes or fails (root sessions only; interruptions by the user are ignored),
+- OpenCode asks for a permission (Allow once / Always / Deny right from the notification),
+- the agent asks a question (form).
+
+It also lets OpenCody send a test notification through the server (since 0.3.0), so the app can check the whole path: OpenCode server → relay → APNs → device.
+
+The push goes through the OpenCody relay; the relay only sees ciphertext. No runtime dependencies.
+
+## 1. Get a pairing string
+
+OpenCody → server settings → *Push notifications* → *Pair*. Copy the single-line pairing string. It is a credential: treat it like a password. One string per device (iPhone or iPad).
+
+## 2. Install the plugin (self-hosted V2 server)
+
+```sh
+opencode plugin add opencody-notify
+```
+
+This adds it to the global config (`~/.config/opencode/opencode.jsonc`, applies to every project). Equivalent by hand, globally or per project (`<project>/opencode.jsonc`):
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencody-notify",
+      "options": {
+        "label": "homelab",                           // shown in the notification; default: hostname
+        "pairings": ["<pairing string device 1>", "<pairing string device 2>"]  // optional, see env below
+      }
+    }
+  ]
+}
+```
+
+### Fallback: local directory
+
+To keep a copy on disk (offline servers, baked into an image), unpack the package into a directory and point `package` at it:
+
+```sh
+mkdir -p /opt/opencody-notify && cd /opt/opencody-notify
+npm pack opencody-notify && tar -xzf opencody-notify-*.tgz --strip-components=1 && rm opencody-notify-*.tgz
+```
+
+```jsonc
+{ "plugins": [{ "package": "/opt/opencody-notify", "options": { "label": "homelab" } }] }  // absolute path, "./relative" or file://
+```
+
+OpenCode loads a local directory plugin from `<dir>/server.js` (or `<dir>/index.*`), not from `package.json` exports; `server.js` re-exports `dist/index.js`.
+
+## 3. Configuration via environment
+
+| Variable | Meaning |
+|---|---|
+| `OPENCODY_PAIRING` | one or more pairing strings, separated by commas, spaces or newlines. Merged with `options.pairings`. |
+| `OPENCODY_SERVER_LABEL` | label if `options.label` is not set |
+| `OPENCODY_DEBUG=1` | log every received event type |
+
+Without any valid pairing the plugin logs a warning and stays idle.
+
+### Docker / Coolify (OpenCode server in a container)
+
+Add the plugin to the config of the user running OpenCode in the container and pass the pairing as a secret env var:
+
+```jsonc
+// ~/.config/opencode/opencode.jsonc
+{ "plugins": [{ "package": "opencody-notify", "options": { "label": "coolify-opencode" } }] }
+```
+
+To avoid a download at startup, bake it in with the local-directory fallback above (`RUN mkdir -p /opt/opencody-notify && cd /opt/opencody-notify && npm pack opencody-notify && tar …`) and use `"package": "/opt/opencody-notify"`.
+
+Environment (Coolify → *Environment Variables*, mark as secret): `OPENCODY_PAIRING=<string1>,<string2>`.
+
+The server must be able to reach `https://push.willsoftwaresolutions.de` (outbound HTTPS).
+
+## 4. Behaviour and safety
+
+- Plugins are instantiated per OpenCode location (project directory); each instance only sees its own project's events, so there are no duplicate pushes across projects.
+- Every event is handled in the background with a 5 s timeout for session lookup and for the relay request; errors are logged (`[opencody-notify] …` on stderr), never thrown. The event subscription is re-opened automatically if it ends.
+- Duplicate events (same type, session, request) within 15 s produce one push.
+- Each push carries a dedupe key (`<sessionID>@<idle time>` or `req:<requestID>`) inside the ciphertext and a SHA-256 prefix of it as APNs collapse id, so OpenCody shows one notification per event even when the app also notices it live.
+- Relay answers `401`/`410` mean the pairing was removed: re-pair in OpenCody and replace the string.
+
+## 5. Test notification (OpenCody → server → device)
+
+OpenCody's *Send Test Notification* calls the plugin through OpenCode's plugin RPC route (OpenCode 2.1 or later), behind the server's normal authentication:
+
+```
+POST /api/rpc/opencody-notify/test   {"input": {"deviceId": "<deviceId from the pairing string>"}}
+→ 200 {"output": {"server": "<label>"}}                                    push sent, relay accepted it
+→ 400 {"type": "not_paired", "data": {"pairings": <n>}, …}                 no pairing for this device on this server
+→ 400 {"type": "relay_failed", "data": {"status": <relay status, 0 = unreachable>}, …}
+→ 400 {"type": "rpc.unavailable", …}                                       plugin not loaded, or older than 0.3.0
+```
+
+It sends one encrypted message of type `test` to that device only. No session, no LLM call, nothing stored on the server. The route is answered at the server's default location (its working directory), so install the plugin globally (`opencode plugin add`) for the test to find it.
+
+## Development
+
+Protocol: `SPEC.md` in the source repository.
+
+```sh
+npm test          # node --test (unit tests incl. crypto test vectors)
+npm run typecheck
+swift test/cryptokit-verify.swift test/vectors.json   # vectors vs. Apple CryptoKit (macOS)
+node ../integration/e2e.ts                             # real OpenCode 2.1.4 + relay + fake APNs (needs npm run build)
+```

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import { type Pairing } from "./protocol.ts";
+export interface OpenCodeEvent {
+    id?: string;
+    type: string;
+    created?: number;
+    location?: {
+        directory?: string;
+    };
+    data?: any;
+}
+interface SessionInfo {
+    id: string;
+    parentID?: string;
+    title?: string;
+    location?: {
+        directory?: string;
+    };
+    time?: {
+        idle?: number;
+    };
+}
+interface RpcCallContext {
+    error(type: string, message: string, data?: unknown): unknown;
+}
+export interface PluginContext {
+    options?: Record<string, unknown>;
+    location?: {
+        directory?: string;
+    };
+    event: {
+        subscribe(options?: {
+            signal?: AbortSignal;
+        }): AsyncIterable<OpenCodeEvent>;
+    };
+    session: {
+        get(input: {
+            sessionID: string;
+        }): Promise<SessionInfo>;
+    };
+    /** OpenCode serves registered methods at `POST /api/rpc/<id>/<method>` (2.1+). */
+    rpc?: {
+        register(definition: object, handlers: Record<string, (input: any, context: RpcCallContext) => Promise<unknown>>): Promise<{
+            dispose(): Promise<void>;
+        }>;
+    };
+}
+/**
+ * `POST /api/rpc/opencody-notify/test {"input":{"deviceId":"…"}}` sends a test push to that
+ * device's pairing, so OpenCody can check the whole path server → relay → APNs → device.
+ */
+export declare const RPC: {
+    readonly id: "opencody-notify";
+    readonly methods: {
+        readonly test: {
+            readonly input: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly deviceId: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["deviceId"];
+            };
+            readonly output: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly server: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["server"];
+            };
+            readonly errors: {
+                readonly not_paired: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly pairings: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly required: readonly ["pairings"];
+                };
+                readonly relay_failed: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly status: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly required: readonly ["status"];
+                };
+            };
+        };
+    };
+    readonly events: {};
+};
+export type TestResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: "not_paired";
+    pairings: number;
+} | {
+    ok: false;
+    error: "relay_failed";
+    status: number;
+    message: string;
+};
+export interface NotifierOptions {
+    pairings: Pairing[];
+    label: string;
+    getSession: (sessionID: string) => Promise<SessionInfo | undefined>;
+    fetch?: typeof fetch;
+    log?: (message: string) => void;
+    timeoutMs?: number;
+    dedupeMs?: number;
+    now?: () => number;
+}
+export declare function createNotifier(options: NotifierOptions): {
+    onEvent(event: OpenCodeEvent): Promise<void>;
+    sendTest(deviceId: string): Promise<TestResult>;
+};
+export declare function loadConfig(options?: Record<string, unknown>, env?: Record<string, string | undefined>): {
+    pairings: Pairing[];
+    label: string;
+    errors: string[];
+};
+declare const _default: {
+    id: string;
+    setup(ctx: PluginContext): () => void;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,244 @@
+import { hostname } from "node:os";
+import { CATEGORY, collapseId, encodeMessage, parsePairing, seal, splitPairings } from "./protocol.js";
+/**
+ * `POST /api/rpc/opencody-notify/test {"input":{"deviceId":"…"}}` sends a test push to that
+ * device's pairing, so OpenCody can check the whole path server → relay → APNs → device.
+ */
+export const RPC = {
+    id: "opencody-notify",
+    methods: {
+        test: {
+            input: { type: "object", properties: { deviceId: { type: "string" } }, required: ["deviceId"] },
+            output: { type: "object", properties: { server: { type: "string" } }, required: ["server"] },
+            errors: {
+                // Error data is required: OpenCode validates it against these schemas.
+                not_paired: { type: "object", properties: { pairings: { type: "number" } }, required: ["pairings"] },
+                relay_failed: { type: "object", properties: { status: { type: "number" } }, required: ["status"] },
+            },
+        },
+    },
+    events: {},
+};
+const SKIPPED_INTERRUPTS = new Set(["user", "superseded"]);
+/**
+ * The session's `time.idle` for this run end, which OpenCody's catch-up keys on. OpenCode sets
+ * idle = max(created, previous idle + 1) when it projects the event; an older idle means the
+ * lookup ran before that, so the event time is the new value.
+ * ponytail: a previous run ending in the same millisecond, before projection, yields its key.
+ */
+function runEnd(session, created) {
+    const idle = session?.time?.idle;
+    return idle !== undefined && idle >= created ? idle : created;
+}
+const withTimeout = (promise, ms) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), ms).unref?.())]);
+export function createNotifier(options) {
+    const { pairings, label, getSession, fetch: doFetch = fetch, log = () => { }, timeoutMs = 5000, dedupeMs = 15_000 } = options;
+    const now = options.now ?? Date.now;
+    const recent = new Map();
+    /** Walks up parentID links; undefined session info means the lookup failed. */
+    async function lineage(sessionID) {
+        let current = await getSession(sessionID).catch(() => undefined);
+        const own = current;
+        for (let hops = 0; current?.parentID && hops < 8; hops++) {
+            const parent = await getSession(current.parentID).catch(() => undefined);
+            if (!parent)
+                break;
+            current = parent;
+        }
+        return { own, root: current };
+    }
+    async function toMessage(event) {
+        const data = event.data ?? {};
+        let type;
+        let sessionID;
+        let text;
+        let requestID;
+        switch (event.type) {
+            case "session.execution.succeeded":
+                ;
+                [type, sessionID, text] = ["session.finished", data.sessionID, "Session finished"];
+                break;
+            case "session.execution.failed":
+                ;
+                [type, sessionID, text] = ["session.failed", data.sessionID, data.error?.message || "Session failed"];
+                break;
+            case "session.execution.interrupted":
+                if (SKIPPED_INTERRUPTS.has(data.reason))
+                    return undefined;
+                [type, sessionID, text] = ["session.failed", data.sessionID, `Interrupted (${data.reason})`];
+                break;
+            case "permission.asked":
+                type = "permission.asked";
+                sessionID = data.sessionID;
+                requestID = data.id;
+                text = data.message || [data.action, (data.resources ?? []).join(", ")].filter(Boolean).join(": ");
+                break;
+            case "form.created":
+                type = "form.asked";
+                sessionID = data.form?.sessionID;
+                requestID = data.form?.id;
+                // The question tool titles every form "Questions"; the actual question is the field description.
+                text = data.form?.fields?.[0]?.description || data.form?.title || "Question";
+                if (data.form?.fields?.length > 1)
+                    text += ` (+${data.form.fields.length - 1} more)`;
+                break;
+            default:
+                return undefined;
+        }
+        if (typeof sessionID !== "string")
+            return undefined;
+        const { own, root } = await lineage(sessionID);
+        // Subagent runs finish constantly; only root runs are worth a push. Permission and form
+        // requests from subagents still block the run, so they are always sent.
+        if (type.startsWith("session.") && own?.parentID)
+            return undefined;
+        const ts = event.created ?? now();
+        return {
+            v: 1,
+            type,
+            server: label,
+            // Durable session.execution.* events carry no location; the session record does.
+            directory: event.location?.directory ?? own?.location?.directory,
+            sessionID,
+            ...(root && root.id !== sessionID ? { rootSessionID: root.id } : {}),
+            ...(root?.title ? { title: root.title } : {}),
+            text,
+            ...(requestID ? { requestID } : {}),
+            key: requestID ? `req:${requestID}` : `${sessionID}@${Math.trunc(runEnd(own, ts))}`,
+            ts,
+        };
+    }
+    function duplicate(message) {
+        const t = now();
+        for (const [key, at] of recent)
+            if (t - at > dedupeMs)
+                recent.delete(key);
+        const key = `${message.type}:${message.sessionID}:${message.requestID ?? ""}`;
+        if (recent.has(key))
+            return true;
+        recent.set(key, t);
+        return false;
+    }
+    async function post(pairing, message) {
+        const ciphertext = seal(Buffer.from(pairing.key, "base64url"), pairing.deviceId, encodeMessage(message));
+        const res = await doFetch(`${pairing.relay}/v1/push`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${pairing.secret}` },
+            body: JSON.stringify({
+                deviceId: pairing.deviceId,
+                category: CATEGORY[message.type],
+                ciphertext,
+                ...(message.key ? { collapseId: collapseId(message.key) } : {}),
+            }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            const hint = res.status === 401 || res.status === 410 ? " (pairing revoked or invalid, re-pair in OpenCody)" : "";
+            log(`relay answered ${res.status} for device ${pairing.deviceId.slice(0, 6)}…${hint}`);
+        }
+        return res.status;
+    }
+    return {
+        async onEvent(event) {
+            try {
+                const message = await withTimeout(toMessage(event), timeoutMs);
+                if (!message || duplicate(message))
+                    return;
+                const results = await Promise.allSettled(pairings.map((pairing) => post(pairing, message)));
+                for (const result of results)
+                    if (result.status === "rejected")
+                        log(`push failed: ${result.reason?.message}`);
+            }
+            catch (error) {
+                log(`event handling failed: ${error?.message}`);
+            }
+        },
+        async sendTest(deviceId) {
+            const pairing = pairings.find((p) => p.deviceId === deviceId);
+            if (!pairing)
+                return { ok: false, error: "not_paired", pairings: pairings.length };
+            const message = { v: 1, type: "test", server: label, sessionID: "", title: "OpenCody", text: "Test notification from your server. Push works.", ts: now() };
+            try {
+                const status = await post(pairing, message);
+                return status >= 200 && status < 300 ? { ok: true } : { ok: false, error: "relay_failed", status, message: `relay answered ${status}` };
+            }
+            catch (error) {
+                return { ok: false, error: "relay_failed", status: 0, message: `relay not reachable: ${error?.message}` };
+            }
+        },
+    };
+}
+export function loadConfig(options = {}, env = process.env) {
+    const raw = [...splitPairings(options.pairings ?? options.pairing), ...splitPairings(env.OPENCODY_PAIRING)];
+    const pairings = [];
+    const errors = [];
+    for (const value of new Set(raw)) {
+        try {
+            pairings.push(parsePairing(value));
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
+    }
+    const label = (typeof options.label === "string" && options.label) || env.OPENCODY_SERVER_LABEL || hostname();
+    return { pairings, label, errors };
+}
+const log = (message) => console.error(`[opencody-notify] ${message}`);
+export default {
+    id: "opencody-notify",
+    setup(ctx) {
+        const { pairings, label, errors } = loadConfig(ctx.options);
+        for (const error of errors)
+            log(`ignoring pairing: ${error}`);
+        const notifier = createNotifier({
+            pairings,
+            label,
+            log,
+            getSession: (sessionID) => ctx.session.get({ sessionID }),
+        });
+        // Registered even without pairings, so OpenCody can tell "plugin missing" from "this device's pairing missing".
+        const registration = ctx.rpc
+            ?.register(RPC, {
+            test: async ({ deviceId }, { error }) => {
+                const result = await notifier.sendTest(deviceId);
+                if (result.ok)
+                    return { server: label };
+                if (result.error === "not_paired")
+                    return error("not_paired", `no pairing for this device on "${label}" (${result.pairings} configured)`, { pairings: result.pairings });
+                return error("relay_failed", result.message, { status: result.status });
+            },
+        })
+            .catch((error) => log(`test endpoint unavailable: ${error?.message}`));
+        const unregister = () => void registration?.then((r) => r?.dispose()).catch(() => { });
+        if (!pairings.length) {
+            log("no valid pairing configured (OPENCODY_PAIRING or plugin option `pairings`); push disabled");
+            return unregister;
+        }
+        const debug = process.env.OPENCODY_DEBUG === "1";
+        const controller = new AbortController();
+        void (async () => {
+            if (debug)
+                log(`subscribing at ${JSON.stringify(ctx.location)}`);
+            while (!controller.signal.aborted) {
+                try {
+                    for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+                        if (debug)
+                            log(`event ${event.type}`);
+                        void notifier.onEvent(event);
+                    }
+                }
+                catch (error) {
+                    if (!controller.signal.aborted)
+                        log(`event stream error: ${error?.message}`);
+                }
+                if (!controller.signal.aborted)
+                    await new Promise((resolve) => setTimeout(resolve, 2000));
+            }
+        })();
+        log(`push enabled for ${pairings.length} device(s) as "${label}"`);
+        return () => {
+            controller.abort();
+            unregister();
+        };
+    },
+};

package/dist/protocol.d.ts

@@ -0,0 +1,37 @@
+export interface Pairing {
+    v: 1;
+    relay: string;
+    deviceId: string;
+    secret: string;
+    key: string;
+}
+export type PushType = "session.finished" | "session.failed" | "permission.asked" | "form.asked" | "test";
+export type Category = "OC_SESSION" | "OC_PERMISSION" | "OC_FORM";
+export interface Message {
+    v: 1;
+    type: PushType;
+    server: string;
+    directory?: string;
+    sessionID: string;
+    rootSessionID?: string;
+    title?: string;
+    text: string;
+    requestID?: string;
+    /** Dedupe key shared with OpenCody's local alerts: `<sessionID>@<time.idle>` or `req:<requestID>`. */
+    key?: string;
+    ts: number;
+}
+export declare const CATEGORY: Record<PushType, Category>;
+export declare const MAX_PLAINTEXT = 2048;
+/** APNs collapse id for a dedupe key: hashed, so the relay and Apple never see session or request IDs. */
+export declare const collapseId: (key: string) => string;
+export declare function parsePairing(input: string): Pairing;
+export declare function encodePairing(pairing: Omit<Pairing, "v">): string;
+/** Pairing strings in env/options may be separated by commas or whitespace. */
+export declare function splitPairings(value: unknown): string[];
+export declare const aad: (deviceId: string) => Buffer<ArrayBuffer>;
+/** Output is base64(nonce[12] || ciphertext || tag[16]) = CryptoKit `AES.GCM.SealedBox.combined`. */
+export declare function seal(key: Buffer, deviceId: string, plaintext: Buffer, nonce?: NonSharedBuffer): string;
+export declare function open(key: Buffer, deviceId: string, combined: string): Buffer<ArrayBuffer>;
+/** Serializes a message, shrinking free-text fields until it fits MAX_PLAINTEXT bytes. */
+export declare function encodeMessage(message: Message): Buffer;

package/dist/protocol.js

@@ -0,0 +1,88 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+export const CATEGORY = {
+    "session.finished": "OC_SESSION",
+    "session.failed": "OC_SESSION",
+    "permission.asked": "OC_PERMISSION",
+    "form.asked": "OC_FORM",
+    test: "OC_SESSION",
+};
+export const MAX_PLAINTEXT = 2048;
+/** APNs collapse id for a dedupe key: hashed, so the relay and Apple never see session or request IDs. */
+export const collapseId = (key) => createHash("sha256").update(key, "utf8").digest("hex").slice(0, 32);
+const B64URL = /^[A-Za-z0-9_-]+$/;
+export function parsePairing(input) {
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(input.trim(), "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Error("pairing string is not base64url JSON");
+    }
+    if (value?.v !== 1)
+        throw new Error("unsupported pairing version");
+    const { relay, deviceId, secret, key } = value;
+    if (typeof relay !== "string" || !/^https?:\/\/[^/]+/.test(relay))
+        throw new Error("invalid relay url");
+    for (const [name, field] of Object.entries({ deviceId, secret, key }))
+        if (typeof field !== "string" || !B64URL.test(field))
+            throw new Error(`invalid ${name}`);
+    if (Buffer.from(key, "base64url").length !== 32)
+        throw new Error("key must be 32 bytes");
+    return { v: 1, relay: relay.replace(/\/+$/, ""), deviceId, secret, key };
+}
+export function encodePairing(pairing) {
+    return Buffer.from(JSON.stringify({ v: 1, ...pairing })).toString("base64url");
+}
+/** Pairing strings in env/options may be separated by commas or whitespace. */
+export function splitPairings(value) {
+    const list = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+    return list.flatMap((item) => (typeof item === "string" ? item.split(/[\s,]+/) : [])).filter(Boolean);
+}
+export const aad = (deviceId) => Buffer.from(`opencody-push:v1:${deviceId}`, "utf8");
+// AES-256-GCM rather than ChaCha20-Poly1305: OpenCode runs plugins on Bun, whose node:crypto lacks ChaCha.
+/** Output is base64(nonce[12] || ciphertext || tag[16]) = CryptoKit `AES.GCM.SealedBox.combined`. */
+export function seal(key, deviceId, plaintext, nonce = randomBytes(12)) {
+    const cipher = createCipheriv("aes-256-gcm", key, nonce, { authTagLength: 16 });
+    cipher.setAAD(aad(deviceId));
+    const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return Buffer.concat([nonce, body, cipher.getAuthTag()]).toString("base64");
+}
+export function open(key, deviceId, combined) {
+    const data = Buffer.from(combined, "base64");
+    const decipher = createDecipheriv("aes-256-gcm", key, data.subarray(0, 12), { authTagLength: 16 });
+    decipher.setAAD(aad(deviceId));
+    decipher.setAuthTag(data.subarray(data.length - 16));
+    return Buffer.concat([decipher.update(data.subarray(12, data.length - 16)), decipher.final()]);
+}
+const cut = (value, max) => {
+    const chars = Array.from(value);
+    return chars.length <= max ? value : chars.slice(0, max - 1).join("") + "…";
+};
+// Keep the tail of paths: the project folder name is the informative part.
+const cutStart = (value, max) => {
+    const chars = Array.from(value);
+    return chars.length <= max ? value : "…" + chars.slice(chars.length - max + 1).join("");
+};
+/** Serializes a message, shrinking free-text fields until it fits MAX_PLAINTEXT bytes. */
+export function encodeMessage(message) {
+    const m = { ...message };
+    m.server = cut(m.server, 64);
+    if (m.title)
+        m.title = cut(m.title, 120);
+    if (m.directory)
+        m.directory = cutStart(m.directory, 200);
+    m.text = cut(m.text, 400);
+    for (;;) {
+        const bytes = Buffer.from(JSON.stringify(m), "utf8");
+        if (bytes.length <= MAX_PLAINTEXT)
+            return bytes;
+        if (Array.from(m.text).length > 20)
+            m.text = cut(m.text, Math.floor(Array.from(m.text).length / 2));
+        else if (m.title && Array.from(m.title).length > 20)
+            m.title = cut(m.title, Math.floor(Array.from(m.title).length / 2));
+        else if (m.directory && Array.from(m.directory).length > 20)
+            m.directory = cutStart(m.directory, Math.floor(Array.from(m.directory).length / 2));
+        else
+            throw new Error("message does not fit");
+    }
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "opencody-notify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "OpenCode V2 server plugin: end-to-end encrypted push notifications to OpenCody (iOS) via the OpenCody push relay",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "homepage": "https://willsoftwaresolutions.de",
+  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./dist/index.js"
+  },
+  "files": ["dist", "server.js"],
+  "engines": { "node": ">=22.18" },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/server.js

@@ -0,0 +1,2 @@
+// Entry point for local-directory installs: OpenCode resolves <dir>/server, not package exports.
+export { default } from "./dist/index.js"