@sansavision/yousaid-server 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `@sansavision/yousaid-server` are recorded here. The
+project follows semantic versioning for the stable surface listed in README.md.
+
+## 0.2.0
+
+First npm release.
+
+- Ships compiled ES2022 JavaScript with TypeScript declarations and declaration maps.
+- Stable: `createYouSaidIdentityToken`, `IdentityClaims` and `IdentityTokenOptions`.
+- `keyId` is required; tokens last 600 seconds by default and at most 900.

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 Sansa Group AB
+
+All rights reserved, Sansa Group AB. Licence terms pending owner and legal review.
+
+No licence is granted to use, copy, modify or distribute this software until
+Sansa Group AB publishes licence terms for it.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @sansavision/yousaid-server
 
-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.
+Server-side helper for YouSaid: sign a short-lived end-user identity token so
+your browser code can send signals and read the inbox without ever holding your
+product signing secret. Runs on Node 20 or later, Cloudflare Workers, Deno, Bun
+and any runtime with Web Crypto.
+
+```sh
+npm install @sansavision/yousaid-server
+```
+
+## Mint a token
+
+```ts
+import { createYouSaidIdentityToken } from "@sansavision/yousaid-server";
+
+const token = await createYouSaidIdentityToken(
+  {
+    sub: user.id,           // your stable user id
+    org_id: "org_...",      // your YouSaid workspace
+    product_id: "prd_...",  // the product the signal belongs to
+    email: user.email,      // optional, verified email; links earlier anonymous history
+    name: user.name,        // optional
+    locale: "en",           // optional
+    account_id: "acct_...", // optional, the customer account
+  },
+  process.env.YOUSAID_SIGNING_SECRET!,
+  { keyId: process.env.YOUSAID_KEY_ID! },
+);
+```
+
+Serve it from an authenticated route, for example `GET /api/yousaid-token`, with
+`cache-control: no-store`, and pass a function that fetches it to
+`YouSaidClient` or `YouSaidProvider`.
+
+| Option | Meaning |
+| --- | --- |
+| `keyId` | Required. The key id issued with your product signing secret. Tokens are verified by this id. |
+| `audience` | Defaults to `yousaid`. |
+| `expiresInSeconds` | Defaults to 600, capped at 900. |
+
+- Tokens are HS256 JWTs with a random nonce. Each state-changing request consumes the nonce, so mint a fresh token per write.
+- Never ship the signing secret to the browser.
+- Rotating the signing credential keeps the previous key valid for an overlap window so your servers can roll over.
+
+## Stability
+
+Version 0.2.0 marks the whole package as **stable** under semantic versioning:
+`createYouSaidIdentityToken` and its types `IdentityClaims` and
+`IdentityTokenOptions`.
+
+## Licence
+
+`UNLICENSED`. All rights reserved, Sansa Group AB. Licence terms are pending
+owner and legal review; see LICENSE.
+
+Documentation: https://yousaid.dev/docs/sdk

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export type IdentityClaims = {
+    sub: string;
+    org_id: string;
+    product_id: string;
+    locale?: string;
+    account_id?: string;
+    /** Verified email. When present, YouSaid links this person's earlier anonymous history for the same email. */
+    email?: string;
+    name?: string;
+};
+export type IdentityTokenOptions = {
+    /** Key id of the product signing credential (required: tokens are verified by this id). */
+    keyId: string;
+    audience?: string;
+    /** Capped at 900 seconds. */
+    expiresInSeconds?: number;
+};
+export declare function createYouSaidIdentityToken(claims: IdentityClaims, secret: string, options: IdentityTokenOptions): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8GAA8G;IAC9G,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAoBjB"}

package/dist/index.js

@@ -0,0 +1,30 @@
+export async function createYouSaidIdentityToken(claims, secret, options) {
+    // YouSaid looks the signing key up by `kid`; there is no server-side "default" key, so a missing id could never verify.
+    if (!options?.keyId || typeof options.keyId !== "string" || options.keyId === "default") {
+        throw new TypeError("createYouSaidIdentityToken requires options.keyId: the YOUSAID_KEY_ID value issued with your product signing secret.");
+    }
+    const issuedAt = Math.floor(Date.now() / 1000);
+    const expiresIn = Math.min(options.expiresInSeconds ?? 600, 900);
+    const header = encode({ alg: "HS256", typ: "JWT", kid: options.keyId });
+    const payload = encode({
+        ...claims,
+        iss: "yousaid-customer-server",
+        aud: options.audience ?? "yousaid",
+        iat: issuedAt,
+        exp: issuedAt + expiresIn,
+        nonce: crypto.randomUUID(),
+    });
+    const input = `${header}.${payload}`;
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(input));
+    return `${input}.${base64Url(new Uint8Array(signature))}`;
+}
+function encode(value) {
+    return base64Url(new TextEncoder().encode(JSON.stringify(value)));
+}
+function base64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@sansavision/yousaid-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Server-side YouSaid helpers: sign short-lived end-user identity tokens.",
+  "private": false,
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sansa-Organisation/yousaid.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://yousaid.dev/docs/sdk",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}