@everframe/identity 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScriptX
+
+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/NOTICE

@@ -0,0 +1,8 @@
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: 2026 ScriptX
+
+Everframe
+SPDX-FileCopyrightText: 2026 ScriptX
+
+This product includes software developed by ScriptX
+(https://github.com/scriptx-com/everframe).

package/README.md

@@ -0,0 +1,103 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-FileCopyrightText: 2026 ScriptX -->
+
+# @everframe/identity
+
+Mint [Everframe](https://everframe.dev) identity tokens from any runtime.
+
+One `createIdentityHandler` call returns a standard
+`(Request) => Promise<Response>` — which is simultaneously a Next App Router
+handler, a Cloudflare Worker, a Vercel/Netlify Edge function, a Supabase Edge
+Function and a Deno/Bun handler.
+
+```ts
+// app/api/everframe-identity/route.ts
+import { createIdentityHandler } from '@everframe/identity';
+
+const handler = createIdentityHandler({
+  secret: process.env.EVERFRAME_IDENTITY_SECRET!,
+  projectId: process.env.EVERFRAME_PROJECT_ID!,
+  resolveUser: async (req) => {
+    const user = await getSessionUser(req);   // cookie, bearer, anything
+    return user ? { id: user.id, email: user.email, name: user.name } : null;
+  },
+});
+
+// Export for BOTH verbs. A cross-origin request carrying `Authorization` is
+// ALWAYS preflighted with an OPTIONS request first — exporting only GET lets
+// Next answer that preflight itself with a bare `Allow` header, so the
+// handler's CORS headers (see "Cross-origin" below) never reach the browser
+// and recognition silently stops working for every cross-origin caller.
+export { handler as GET, handler as OPTIONS };
+```
+
+Then point the SDK at it:
+
+```tsx
+<EverframeProvider
+  config={{ apiKey }}
+  identity={{ endpoint: '/api/everframe-identity', key: user?.id }}
+>
+```
+
+## Auth is a callback, not a cookie
+
+`resolveUser` receives the `Request`. Cookies are one implementation; a bearer
+token is another:
+
+```ts
+resolveUser: (req) => verifyAccessToken(req.headers.get('authorization'))
+```
+
+On the client, `headers` is re-invoked on **every** mint, so a rotating access
+token is never captured stale:
+
+```tsx
+identity={{
+  endpoint: 'https://api.example.com/everframe-identity',
+  key: user?.id,
+  headers: async () => ({ Authorization: `Bearer ${await getAccessToken()}` }),
+}}
+```
+
+## Cross-origin
+
+Pass `allowedOrigins` to answer preflights and echo matched origins. Absent, the
+handler is same-origin only. `'*'` throws — a wildcard origin on an endpoint
+that returns identity tokens would expose them to any site.
+
+```ts
+createIdentityHandler({ …, allowedOrigins: ['https://app.example.com'] })
+```
+
+## Node
+
+```ts
+import { toNodeHandler } from '@everframe/identity/node';
+const nodeHandler = (req, res) => void toNodeHandler(handler)(req, res);
+
+// Register for BOTH verbs — or use app.all(...) — for the same reason as the
+// Next example above: a cross-origin request carrying `Authorization` is
+// ALWAYS preflighted with OPTIONS first. Registering only `.get(...)` means
+// Express answers OPTIONS with a 404 before it ever reaches the handler, so
+// its CORS headers never appear and recognition silently stops working for
+// every cross-origin caller.
+app.get('/api/everframe-identity', nodeHandler);
+app.options('/api/everframe-identity', nodeHandler);
+```
+
+## Responses
+
+| Case | Response |
+|---|---|
+| User resolves | `200 { token, expiresAt }` (`expiresAt` is ms epoch) |
+| Nobody signed in | `200 { token: null }` |
+| `user.id` empty or >255 chars | `200 { token: null, reason: 'subject_too_long' }` |
+| `resolveUser` throws | `500`, empty body |
+
+Every response carries `Cache-Control: no-store`. A signed-out user is a normal
+state, not an error — all `token: null` cases read as "anonymous" to the SDK.
+
+## Licence
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/** The person a token is minted for. `id` becomes `sub`. */
+interface IdentityUser {
+    /** Stable identifier. Non-empty, <=255 chars after trimming. */
+    id: string;
+    /** Optional. Dropped when empty or over 320 chars, never an error. */
+    email?: string;
+    /** Optional. Dropped when empty or over 320 chars, never an error. */
+    name?: string;
+}
+/** `SUBJECT_MAX` in the server identity-token verifier. */
+declare const SUBJECT_MAX = 255;
+/** `CLAIM_MAX` in the server identity-token verifier. */
+declare const CLAIM_MAX = 320;
+/** `IDENTITY_TOKEN_MAX_TTL_SEC` in the server identity-token verifier. */
+declare const MAX_TTL_SECONDS = 600;
+/** Well inside the ceiling, so ordinary clock drift never approaches it. */
+declare const DEFAULT_TTL_SECONDS = 300;
+
+interface MintOptions {
+    secret: string;
+    projectId: string;
+    user: IdentityUser;
+    ttlSeconds?: number;
+    /**
+     * Test-only clock injection. Production callers omit it.
+     * @internal
+     */
+    now?: Date;
+}
+declare function mintIdentityToken(opts: MintOptions): Promise<string>;
+
+type ResolveUser = (req: Request) => IdentityUser | null | Promise<IdentityUser | null>;
+interface HandlerOptions {
+    secret: string;
+    projectId: string;
+    resolveUser: ResolveUser;
+    ttlSeconds?: number;
+    /**
+     * Exact-match origin allowlist. ABSENT means no CORS headers at all —
+     * same-origin only, which is the safe default. '*' throws.
+     */
+    allowedOrigins?: string[];
+    /** Only meaningful with `allowedOrigins`. The cookie case. */
+    allowCredentials?: boolean;
+}
+declare function createIdentityHandler(opts: HandlerOptions): (req: Request) => Promise<Response>;
+
+export { CLAIM_MAX, DEFAULT_TTL_SECONDS, type HandlerOptions, type IdentityUser, MAX_TTL_SECONDS, type MintOptions, type ResolveUser, SUBJECT_MAX, createIdentityHandler, mintIdentityToken };

package/dist/index.js

@@ -0,0 +1,170 @@
+import { SignJWT } from 'jose';
+
+// src/mint.ts
+
+// src/types.ts
+var SUBJECT_MAX = 255;
+var CLAIM_MAX = 320;
+var MAX_TTL_SECONDS = 600;
+var DEFAULT_TTL_SECONDS = 300;
+var MIN_SECRET_LENGTH = 32;
+
+// src/mint.ts
+function assertValidSecret(secret) {
+  if (typeof secret !== "string" || secret.trim().length < MIN_SECRET_LENGTH) {
+    throw new Error(
+      `@everframe/identity: secret must be a string of at least ${MIN_SECRET_LENGTH} characters. Generate one in Project settings -> User recognition and read it from your environment.`
+    );
+  }
+}
+function assertValidProjectId(projectId) {
+  if (typeof projectId !== "string" || projectId.trim() === "") {
+    throw new Error("@everframe/identity: projectId must be a non-empty string.");
+  }
+}
+function assertValidTtl(ttlSeconds) {
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0 || ttlSeconds > MAX_TTL_SECONDS) {
+    throw new Error(
+      `@everframe/identity: ttlSeconds must be a positive integer <= ${MAX_TTL_SECONDS}. Everframe rejects longer-lived tokens as ttl_too_long.`
+    );
+  }
+}
+function optionalClaim(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  if (trimmed === "" || trimmed.length > CLAIM_MAX) return void 0;
+  return trimmed;
+}
+function normalizeUser(user) {
+  const sub = typeof user?.id === "string" ? user.id.trim() : "";
+  if (sub === "" || sub.length > SUBJECT_MAX) {
+    throw new SubjectError(
+      `@everframe/identity: user.id must be a non-empty string of at most ${SUBJECT_MAX} characters.`
+    );
+  }
+  return { sub, email: optionalClaim(user.email), name: optionalClaim(user.name) };
+}
+var SubjectError = class extends Error {
+  reason = "subject_too_long";
+};
+async function mintIdentityToken(opts) {
+  const ttlSeconds = opts.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+  assertValidSecret(opts.secret);
+  assertValidProjectId(opts.projectId);
+  assertValidTtl(ttlSeconds);
+  const { sub, email, name } = normalizeUser(opts.user);
+  const iat = Math.floor((opts.now?.getTime() ?? Date.now()) / 1e3);
+  return await new SignJWT({
+    ...email !== void 0 ? { email } : {},
+    ...name !== void 0 ? { name } : {}
+  }).setProtectedHeader({ alg: "HS256" }).setSubject(sub).setAudience(opts.projectId).setIssuedAt(iat).setExpirationTime(iat + ttlSeconds).sign(new TextEncoder().encode(opts.secret));
+}
+
+// src/cors.ts
+var ALLOWED_METHODS = "GET, POST, OPTIONS";
+var ALLOWED_HEADERS = "authorization, content-type";
+var MAX_AGE = "600";
+function isPreflight(req) {
+  return req.method === "OPTIONS" && req.headers.has("access-control-request-method");
+}
+function corsHeadersFor(req, allowedOrigins, allowCredentials) {
+  if (!allowedOrigins || allowedOrigins.length === 0) return null;
+  const headers = new Headers({ vary: "Origin" });
+  const origin = req.headers.get("origin");
+  if (origin === null || !allowedOrigins.includes(origin)) return headers;
+  headers.set("access-control-allow-origin", origin);
+  headers.set("access-control-allow-methods", ALLOWED_METHODS);
+  headers.set("access-control-allow-headers", ALLOWED_HEADERS);
+  headers.set("access-control-max-age", MAX_AGE);
+  if (allowCredentials) headers.set("access-control-allow-credentials", "true");
+  return headers;
+}
+
+// src/handler.ts
+function baseHeaders() {
+  return new Headers({ "cache-control": "no-store" });
+}
+function json(body, status, headers) {
+  headers.set("content-type", "application/json");
+  return new Response(JSON.stringify(body), { status, headers });
+}
+function createIdentityHandler(opts) {
+  const ttlSeconds = opts.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+  assertValidSecret(opts.secret);
+  assertValidProjectId(opts.projectId);
+  assertValidTtl(ttlSeconds);
+  assertValidOrigins(opts.allowedOrigins);
+  return async function identityHandler(req) {
+    const headers = baseHeaders();
+    const cors = corsHeadersFor(req, opts.allowedOrigins, opts.allowCredentials === true);
+    if (cors) for (const [k, v] of cors) headers.set(k, v);
+    if (cors && isPreflight(req)) {
+      return new Response(null, { status: 204, headers });
+    }
+    if (req.method !== "GET" && req.method !== "POST") {
+      return new Response(null, { status: 405, headers });
+    }
+    let user;
+    try {
+      user = await opts.resolveUser(req);
+    } catch {
+      return new Response(null, { status: 500, headers });
+    }
+    if (!user) return json({ token: null }, 200, headers);
+    try {
+      normalizeUser(user);
+    } catch (err) {
+      if (err instanceof SubjectError) {
+        return json({ token: null, reason: err.reason }, 200, headers);
+      }
+      return new Response(null, { status: 500, headers });
+    }
+    const now = /* @__PURE__ */ new Date();
+    const token = await mintIdentityToken({
+      secret: opts.secret,
+      projectId: opts.projectId,
+      user,
+      ttlSeconds,
+      now
+    });
+    return json({ token, expiresAt: now.getTime() + ttlSeconds * 1e3 }, 200, headers);
+  };
+}
+function assertValidOrigins(allowedOrigins) {
+  if (allowedOrigins === void 0) return;
+  if (!Array.isArray(allowedOrigins)) {
+    throw new Error("@everframe/identity: allowedOrigins must be an array of origin strings.");
+  }
+  if (allowedOrigins.includes("*")) {
+    throw new Error(
+      "@everframe/identity: allowedOrigins cannot contain '*'. A wildcard origin combined with credentials is rejected by browsers and would expose identity tokens to any site. List your origins explicitly."
+    );
+  }
+  for (const entry of allowedOrigins) {
+    if (entry.trim().toLowerCase() === "null") {
+      throw new Error(
+        `@everframe/identity: allowedOrigins cannot contain "${entry}". The string "null" is the opaque-origin placeholder shared by sandboxed iframes, data: URLs, file: pages, and some redirect flows \u2014 it does not identify a trusted caller, so allowlisting it would let any of those unrelated contexts read identity tokens. List real origins instead.`
+      );
+    }
+    let url;
+    try {
+      url = new URL(entry);
+    } catch {
+      throw new Error(
+        `@everframe/identity: allowedOrigins entry "${entry}" is not a valid URL. Expected a bare origin like "https://app.example.com".`
+      );
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error(
+        `@everframe/identity: allowedOrigins entry "${entry}" must use http: or https:. Expected a bare origin like "https://app.example.com".`
+      );
+    }
+    if (url.origin !== entry) {
+      throw new Error(
+        `@everframe/identity: allowedOrigins entry "${entry}" must be a bare origin \u2014 no path, query, fragment, or trailing slash. Expected a form like "https://app.example.com".`
+      );
+    }
+  }
+}
+
+export { CLAIM_MAX, DEFAULT_TTL_SECONDS, MAX_TTL_SECONDS, SUBJECT_MAX, createIdentityHandler, mintIdentityToken };

package/dist/node.d.ts

@@ -0,0 +1,13 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+type FetchHandler = (req: Request) => Promise<Response>;
+/**
+ * Adapt a WHATWG handler to Express, Connect, Next Pages Router, or plain
+ * node:http.
+ *
+ *   const handler = toNodeHandler(createIdentityHandler({ … }));
+ *   app.get('/api/everframe-identity', (req, res) => void handler(req, res));
+ */
+declare function toNodeHandler(handler: FetchHandler): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export { toNodeHandler };

package/dist/node.js

@@ -0,0 +1,79 @@
+// src/node.ts
+var MAX_BODY_BYTES = 1024 * 1024;
+var BodyTooLargeError = class extends Error {
+};
+async function readBody(req) {
+  if (req.method !== "POST") return void 0;
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of req) {
+    const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : new Uint8Array(chunk);
+    total += bytes.byteLength;
+    if (total > MAX_BODY_BYTES) {
+      throw new BodyTooLargeError();
+    }
+    chunks.push(bytes);
+  }
+  if (chunks.length === 0) return void 0;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+function toNodeHandler(handler) {
+  return async function nodeHandler(req, res) {
+    try {
+      const host = req.headers.host ?? "localhost";
+      let url;
+      try {
+        url = new URL(req.url ?? "/", `http://${host}`);
+      } catch {
+        url = new URL(req.url ?? "/", "http://localhost");
+      }
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === void 0) continue;
+        if (Array.isArray(value)) for (const v of value) headers.append(key, v);
+        else headers.set(key, value);
+      }
+      let body;
+      try {
+        body = await readBody(req);
+      } catch (err) {
+        if (err instanceof BodyTooLargeError) {
+          if (!res.headersSent) {
+            res.statusCode = 413;
+            res.setHeader("cache-control", "no-store");
+            res.setHeader("connection", "close");
+            res.once("finish", () => req.destroy());
+            res.end();
+          }
+          return;
+        }
+        throw err;
+      }
+      const request = new Request(url, {
+        method: req.method ?? "GET",
+        headers,
+        ...body ? { body } : {}
+      });
+      const response = await handler(request);
+      if (res.headersSent) return;
+      res.statusCode = response.status;
+      response.headers.forEach((value, key) => res.setHeader(key, value));
+      const text = await response.text();
+      res.end(text === "" ? void 0 : text);
+    } catch {
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.setHeader("cache-control", "no-store");
+        res.end();
+      }
+    }
+  };
+}
+
+export { toNodeHandler };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@everframe/identity",
+  "version": "0.3.0",
+  "description": "Mint Everframe identity tokens from any runtime — one handler that works as a Next route, a Cloudflare Worker, an Edge function or a Node server.",
+  "author": {
+    "name": "Scriptx, UAB",
+    "email": "support@everframe.dev",
+    "url": "https://everframe.dev"
+  },
+  "keywords": [
+    "everframe",
+    "identity",
+    "jwt",
+    "authentication",
+    "bug-reporting"
+  ],
+  "homepage": "https://everframe.dev",
+  "bugs": {
+    "url": "https://github.com/scriptx-com/everframe/issues"
+  },
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scriptx-com/everframe.git",
+    "directory": "packages/identity"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "jose": "6.2.5"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.0",
+    "@types/node": "^22.0.0",
+    "publint": "^0.3.0",
+    "tsup": "^8.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "check:publish": "attw --pack . --profile esm-only --ignore-rules cjs-resolves-to-esm && publint",
+    "clean": "rm -rf dist .turbo node_modules/.cache"
+  }
+}