@ozvi/sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozvi contributors
+
+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,24 @@
-# Temporary Holding Version
+# @ozvi/sdk
 
-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.
+Sign [Ozvi](https://ozvi.io) SSO tokens in your backend, so people who are signed in to your app are signed in to the Ozvi widget and board too. Node.js 18+, zero dependencies, MIT.
+
+```sh
+npm i @ozvi/sdk
+```
+
+```js
+import { signOzviToken } from "@ozvi/sdk";
+
+// The widget's token-url, e.g. app.get("/api/ozvi-token", …) or app/api/ozvi-token/route.ts in Next.js
+const token = signOzviToken(
+  { id: user.id, email: user.email, name: user.name,
+    traits: { company: org.name, plan: org.plan, mrr: 2900 } },   // shown to your team only
+  process.env.OZVI_SSO_SECRET,                                       // board settings → Sign-in
+);
+```
+
+- `id` (required) is the person's stable id in your app; `role` can be `member` (default), `team` or `admin`; `locale` sets the board language.
+- Tokens live 10 minutes by default (`{ expiresIn }` in seconds); the widget asks for a fresh one when it needs it.
+- `verifyOzviToken(token, secret)` checks a token the way Ozvi does, handy in tests.
+
+The token is a standard HS256 JWT, so any language can make one without this package: see [Sign people in](https://ozvi.io/docs/widget#sign-in) for Python and PHP.

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Host-app SSO: your backend signs who the user is, Ozvi trusts it.
+ * HS256 JWT with a shared secret (OZVI_SSO_SECRET). No round-trip, no Ozvi account needed.
+ *
+ *   const token = signOzviToken({ id: user.id, email: user.email, name: user.name,
+ *                                 locale: "en", traits: { company: "Acme", plan: "pro", mrr: 2900 } }, process.env.OZVI_SSO_SECRET!);
+ *   // pass it to the widget: <ozvi-widget sso-token="...">  or  https://feedback.example.com/sso?token=...
+ *
+ * `locale` (optional) forces the board language for this user ("sk" | "cs" | "en"), so the board
+ * matches your app. Ignored when the board does not have that language enabled.
+ */
+export interface OzviUser {
+    /** Stable id in YOUR system. Ozvi keys the user on (project, id), never on e-mail alone. */
+    id: string;
+    email?: string;
+    /**
+     * true only if YOUR app has verified that this person owns `email` (a confirmation link or code).
+     * Ozvi then treats them as the same person as someone who signs in to the board with that e-mail
+     * by code (one account, not two); accounts with team or admin rights are never joined. Omit it (or
+     * false) for addresses you have not verified: Ozvi then keeps the two accounts apart.
+     */
+    emailVerified?: boolean;
+    name?: string;
+    avatarUrl?: string;
+    /** "team" can triage and write internal notes, "admin" can also change settings. Defaults to "member". */
+    role?: "member" | "team" | "admin";
+    /** UI language on the board and in e-mails: "sk", "cs" or "en". Omit to let the browser decide. */
+    locale?: "sk" | "cs" | "en";
+    /**
+     * Customer data shown only to your team (item page "who wants it", ideas sorted by MRR, plan filter, MCP for
+     * triage tokens). Known names: `company`, `companyId` (people with the same id count as one company),
+     * `plan`, `mrr` (monthly revenue in cents, integer), `currency` (ISO 4217, default "EUR"). Other keys are
+     * stored as they are (max 30, strings up to 200 chars). Omit `traits` to keep the stored ones; `{}` clears them.
+     */
+    traits?: OzviTraits;
+}
+export interface OzviTraits {
+    company?: string;
+    companyId?: string;
+    plan?: string;
+    /** Monthly recurring revenue in cents (2900 = 29.00). */
+    mrr?: number;
+    /** ISO 4217 currency of `mrr`; "EUR" when missing. */
+    currency?: string;
+    [key: string]: string | number | boolean | null | undefined;
+}
+export interface OzviClaims extends OzviUser {
+    iat: number;
+    exp: number;
+}
+export interface SignOptions {
+    /** Token lifetime in seconds. Short by default — tokens are minted per page load. */
+    expiresIn?: number;
+    now?: () => number;
+}
+export declare function signOzviToken(user: OzviUser, secret: string, opts?: SignOptions): string;
+export declare class OzviTokenError extends Error {
+    readonly reason: "malformed" | "algorithm" | "signature" | "expired" | "claims";
+    constructor(reason: "malformed" | "algorithm" | "signature" | "expired" | "claims");
+}
+/** Used by the Ozvi server. Exported so integrators can test their setup locally. */
+export declare function verifyOzviToken(token: string, secret: string, opts?: {
+    now?: () => number;
+    leewaySeconds?: number;
+}): OzviClaims;

package/dist/index.js

@@ -0,0 +1,59 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const MIN_SECRET = 32;
+const b64url = (b) => Buffer.from(b).toString("base64url");
+const HEADER = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+function assertSecret(secret) {
+    if (typeof secret !== "string" || secret.length < MIN_SECRET) {
+        throw new Error(`Ozvi SSO secret must be at least ${MIN_SECRET} characters`);
+    }
+}
+export function signOzviToken(user, secret, opts = {}) {
+    assertSecret(secret);
+    if (!user.id)
+        throw new Error("Ozvi SSO token needs user.id");
+    const iat = Math.floor((opts.now?.() ?? Date.now()) / 1000);
+    const claims = { ...user, iat, exp: iat + (opts.expiresIn ?? 600) };
+    const body = `${HEADER}.${b64url(JSON.stringify(claims))}`;
+    return `${body}.${createHmac("sha256", secret).update(body).digest("base64url")}`;
+}
+export class OzviTokenError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Invalid Ozvi SSO token: ${reason}`);
+        this.reason = reason;
+    }
+}
+/** Used by the Ozvi server. Exported so integrators can test their setup locally. */
+export function verifyOzviToken(token, secret, opts = {}) {
+    assertSecret(secret);
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new OzviTokenError("malformed");
+    const [h, p, s] = parts;
+    let header;
+    try {
+        header = JSON.parse(Buffer.from(h, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new OzviTokenError("malformed");
+    }
+    if (header.alg !== "HS256")
+        throw new OzviTokenError("algorithm");
+    const expected = createHmac("sha256", secret).update(`${h}.${p}`).digest();
+    const given = Buffer.from(s, "base64url");
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+        throw new OzviTokenError("signature");
+    let claims;
+    try {
+        claims = JSON.parse(Buffer.from(p, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new OzviTokenError("malformed");
+    }
+    if (typeof claims.id !== "string" || !claims.id || typeof claims.exp !== "number")
+        throw new OzviTokenError("claims");
+    const now = Math.floor((opts.now?.() ?? Date.now()) / 1000);
+    if (claims.exp + (opts.leewaySeconds ?? 30) < now)
+        throw new OzviTokenError("expired");
+    return claims;
+}

package/dist/mask.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Masking for what the widget captures (network log, action timeline). Runs in the browser BEFORE
+ * anything is kept in memory, and again on the Ozvi server as a second line of defence.
+ * Dependency-free and small: it ships inside widget.js (20 kB gzip budget).
+ */
+export declare const MASK = "***";
+/** Names of query parameters, JSON keys and form fields whose values never leave the browser. */
+export declare const SECRET_NAME: RegExp;
+/** Free text: JWTs, Authorization-style credentials, e-mail addresses, IBANs and card numbers. */
+export declare function maskText(s: string): string;
+/**
+ * A request or page URL with secrets removed: user:password@ dropped, secret-named query and fragment
+ * parameters masked, tokens/e-mails/card numbers in the path or values masked. Relative URLs stay relative.
+ */
+export declare function maskUrl(raw: string): string;
+/**
+ * A request or response body: JSON gets secret-named keys masked (at any depth) and secret-looking
+ * values masked; a URL-encoded form gets the same per field; anything else is masked as free text.
+ * The result is cut to `limit` characters.
+ */
+export declare function maskBody(body: string, limit?: number): string;
+/**
+ * Where a text contains something that must not appear on a screenshot: JWTs, credentials,
+ * e-mail addresses, IBANs, card numbers (Luhn-checked) and phone numbers. Sorted, non-overlapping
+ * [start, end) ranges; the widget covers them with a solid box in the screenshot's copy of the page.
+ */
+export declare function sensitiveRanges(s: string): [number, number][];

package/dist/mask.js

@@ -0,0 +1,165 @@
+/**
+ * Masking for what the widget captures (network log, action timeline). Runs in the browser BEFORE
+ * anything is kept in memory, and again on the Ozvi server as a second line of defence.
+ * Dependency-free and small: it ships inside widget.js (20 kB gzip budget).
+ */
+export const MASK = "***";
+/** Names of query parameters, JSON keys and form fields whose values never leave the browser. */
+export const SECRET_NAME = /token|secret|passw|pwd|key|auth|session|card|iban|cvv|cvc|otp|pin$|signature|cookie|csrf|xsrf|jwt|bearer|ssn|credential/i;
+const JWT = /\beyJ[\w-]{6,}\.[\w-]{6,}\.[\w-]*/g;
+const BEARER = /\b(Bearer|Basic|Token)\s+[\w~+/.=-]{8,}/gi;
+const EMAIL = /[\w.+-]+@[\w-]+(\.[\w-]+)+/g;
+const IBAN = /\b[A-Z]{2}\d{2}(?:[ ]?[A-Z0-9]{4}){2,7}(?:[ ]?[A-Z0-9]{1,4})?\b/g;
+const CARD = /\b\d(?:[ -]?\d){12,18}\b/g;
+/** Luhn check, so long numbers (timestamps, ids) are not mistaken for card numbers. */
+function luhn(digits) {
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let d = +digits[digits.length - 1 - i];
+        if (i % 2) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return sum % 10 === 0;
+}
+/** Free text: JWTs, Authorization-style credentials, e-mail addresses, IBANs and card numbers. */
+export function maskText(s) {
+    return s
+        .replace(JWT, MASK)
+        .replace(BEARER, (_, kind) => `${kind} ${MASK}`)
+        .replace(EMAIL, MASK)
+        .replace(IBAN, MASK)
+        .replace(CARD, (m) => {
+        const d = m.replace(/\D/g, "");
+        return d.length >= 13 && d.length <= 19 && luhn(d) ? MASK : m;
+    });
+}
+/** `a=1&token=x` → `a=1&token=***`. Keeps the parameter names (useful for debugging), masks values. */
+function maskParams(qs) {
+    return qs.split("&").map((pair) => {
+        const i = pair.indexOf("=");
+        if (i < 0)
+            return maskText(pair);
+        let name = pair.slice(0, i);
+        try {
+            name = decodeURIComponent(name.replace(/\+/g, " "));
+        }
+        catch { /* keep raw */ }
+        if (SECRET_NAME.test(name))
+            return `${pair.slice(0, i)}=${MASK}`;
+        let v = pair.slice(i + 1);
+        try {
+            v = decodeURIComponent(v.replace(/\+/g, " "));
+        }
+        catch { /* keep raw */ }
+        const masked = maskText(v);
+        return masked === v ? pair : `${pair.slice(0, i)}=${encodeURIComponent(masked).replace(/%2A/g, "*")}`;
+    }).join("&");
+}
+/**
+ * A request or page URL with secrets removed: user:password@ dropped, secret-named query and fragment
+ * parameters masked, tokens/e-mails/card numbers in the path or values masked. Relative URLs stay relative.
+ */
+export function maskUrl(raw) {
+    const s = String(raw);
+    const m = /^([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/s.exec(s);
+    if (!m)
+        return maskText(s);
+    let [, path = "", query, hash] = m;
+    path = path.replace(/^([a-z][\w+.-]*:\/\/)[^/@]*@/i, "$1");
+    let decoded = path;
+    try {
+        decoded = decodeURIComponent(path);
+    }
+    catch { /* keep raw */ }
+    // An e-mail or token in the path (`/users/jane@x.com`, `/reset/eyJ…`) is masked even when percent-encoded.
+    let out = maskText(decoded) === decoded ? path : maskText(decoded);
+    if (query !== undefined)
+        out += `?${maskParams(query)}`;
+    if (hash !== undefined) {
+        // OAuth implicit flow puts tokens in the fragment: `#access_token=…` or `#/cb?token=…`.
+        const q = hash.indexOf("?");
+        const [lead, params] = q >= 0 ? [hash.slice(0, q + 1), hash.slice(q + 1)] : /^[!/]*[^=&/]*=/.test(hash) ? ["", hash] : [hash, ""];
+        out += `#${maskText(lead)}${params ? maskParams(params) : ""}`;
+    }
+    return out;
+}
+function maskValue(v, depth) {
+    if (typeof v === "string")
+        return maskText(v);
+    if (!v || typeof v !== "object" || depth > 20)
+        return v;
+    if (Array.isArray(v))
+        return v.map((x) => maskValue(x, depth + 1));
+    const out = {};
+    for (const [k, x] of Object.entries(v))
+        out[k] = SECRET_NAME.test(k) && x !== null && x !== "" ? MASK : maskValue(x, depth + 1);
+    return out;
+}
+/**
+ * A request or response body: JSON gets secret-named keys masked (at any depth) and secret-looking
+ * values masked; a URL-encoded form gets the same per field; anything else is masked as free text.
+ * The result is cut to `limit` characters.
+ */
+export function maskBody(body, limit = 2000) {
+    const s = String(body);
+    let out;
+    const t = s.trim();
+    if (t.startsWith("{") || t.startsWith("[")) {
+        try {
+            out = JSON.stringify(maskValue(JSON.parse(t), 0));
+        }
+        catch {
+            out = maskText(s);
+        }
+    }
+    else if (/^[\w.%+\-[\]]+=[^\s]*(&[\w.%+\-[\]]+=[^\s]*)*$/.test(t)) {
+        out = maskParams(t);
+    }
+    else
+        out = maskText(s);
+    return out.length > limit ? `${out.slice(0, limit)}…` : out;
+}
+/**
+ * Phone numbers for screenshots: 9–15 digits, optional +/00 prefix, spaces, dashes, dots, slashes
+ * or brackets between (dates like "12. 11. 2026" have 8 digits and stay readable).
+ */
+const PHONE = /(^|[^\w+(])((?:\+|00)?\(?\d[\d ()./-]{7,20}\d)(?!\w)/g;
+/**
+ * Where a text contains something that must not appear on a screenshot: JWTs, credentials,
+ * e-mail addresses, IBANs, card numbers (Luhn-checked) and phone numbers. Sorted, non-overlapping
+ * [start, end) ranges; the widget covers them with a solid box in the screenshot's copy of the page.
+ */
+export function sensitiveRanges(s) {
+    const found = [];
+    const add = (re, ok = () => true) => {
+        for (const m of s.matchAll(re))
+            if (ok(m[0]))
+                found.push([m.index, m.index + m[0].length]);
+    };
+    add(JWT);
+    add(BEARER);
+    add(EMAIL);
+    add(IBAN);
+    add(CARD, (m) => { const d = m.replace(/\D/g, ""); return d.length >= 13 && d.length <= 19 && luhn(d); });
+    for (const m of s.matchAll(PHONE)) {
+        const d = m[2].replace(/\D/g, "").length;
+        if (d >= 9 && d <= 15) {
+            const at = m.index + m[1].length;
+            found.push([at, at + m[2].length]);
+        }
+    }
+    found.sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+    const out = [];
+    for (const r of found) {
+        const last = out.at(-1);
+        if (last && r[0] < last[1])
+            last[1] = Math.max(last[1], r[1]);
+        else
+            out.push([r[0], r[1]]);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@ozvi/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Sign Ozvi SSO tokens in your backend (Node.js, zero dependencies). MIT.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mask": {
+      "types": "./dist/mask.d.ts",
+      "import": "./dist/mask.js"
+    }
+  },
+  "homepage": "https://ozvi.io/docs/widget#sign-in",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xzamiska/ozvi.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "ozvi",
+    "sso",
+    "jwt",
+    "feedback"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc -p .",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
+  }
 }